Platform Quickstart
In this guide, we will walk through the process of creating an app to manage tickets using the OS1 Platform. We'll use the Entity service as an example to demonstrate how you can leverage OS1's services to build your application. The steps outlined here will provide visibility to developers on how to get started with OS1 and can be applied to other services available on the platform.
Before you begin, ensure you have the following: ● Access to the OS1 Platform ● A Registered Application ● Authentication credentials (Client ID, Client Secret, Tenant URL, and Tenant ID) ● Access to the OS1 Postman Collection
Let's consider a scenario where you want to create an app to manage tickets. We'll use the Entity service to create and manage ticket entities. The Entity service allows you to define custom entity types, configure their states, and manage entity instances.
To start, we'll create a new Entity Type for tickets. To create an Entity Type, call the CreateEntityType endpoint with the following JSON request body:
This request creates a new Entity Type for tickets with the specified name, category, attributes, and events. It also enables the state machine for the Entity Type.
Next, we'll configure the states and transitions for the ticket Entity Type. Call the RegisterStateMachineConfig endpoint with the following JSON request body:
This request configures the states (open, resolved) and their corresponding substates for the ticket Entity Type. It defines the event codes that trigger transitions between states and sets the TTL (Time-to-Live) for each state.
With the ticket Entity Type and its states configured, we can now create a specific ticket instance by calling the CreateEntity endpoint.
In this example, we created a new entity instance, assigned it a unique code, set its name, owner, category, subcategory, and properties. The API also specifies a callback URL to receive notifications related to the Entity Instance.
Finally, let's transition the state of the ticket instance. Call the ApplyEventToEntity endpoint with the following JSON request body:
In our example, the API applies an event to the Entity Instance, triggering a state transition. The event code "E-101" is used to transition the Entity's state from open:new to open:in_progress.
Now that you have tried creating an Entity using the Entity service, you should have the foundation to interact with the OS1 Platform. With this knowledge, you can explore and utilize additional services like Participant, Container, MTS, Messaging, and more to build your applications. Each service offers unique capabilities that can be leveraged to fit your specific use cases.
To start building and developing your apps, you can refer to the Vehicle Reference App, which serves as a reference app build that leverages the Participant service using the Console. Visit the Github repository at https://github.com/OS1-logistics/vehicle-reference-app to access the Vehicle Reference App. It provides a practical example of implementing and utilizing the OS1 Platform's APIs in a real-world scenario.