The SDK allows to interact with the SpaceTraders API from a Camunda process. It is based on Camunda's REST connector. The SDK eases the usage by providing a connector template.
The connector template is generated from the SpaceTraders OpenAPI. See the openapi module for details.
space-traders-sdk-demo.mp4
- Find the SDK in the Camunda Marketplace
- Click the button "For SAAS". You will be forwarded to the Camunda Web Modeler.
- On the download modal, select a project to publish the connector to.
The connector is now available within the select project. 🚀
- Open the Camunda Web Modeler
- Open a project or create a new one.
- Upload the connector template spacetraders.json (see how)
- Publish the connector template (see how)
The SpaceTraders API has the different endpoints that are split into the following categories:
- Game: register a new agent, get server status
- Agents: get details about an agent
- Contracts: get details about a contract, interact with a contract (e.g. accept, deliver, fulfill)
- Systems: get details about a star system (e.g. waypoints, shipyard, market)
- Fleet: get details about a ship, interact with a ship (e.g. dock, orbit, navigate, extract resources, sell cargo)
- Factions: get details about a faction
The connector can interact with all endpoints. First, you select a category and then an operation to use.
- Add a new task to your process
- Select the SpaceTraders connector as the task type (e.g.
SpaceTraders
) - Select the category in the properties (e.g.
Fleet
) - Select the operation (e.g.
getMyShip - Get Ship
) - Fill the required parameters (e.g.
shipSymbol
) - Optionally, adjust the result expression to customize the resulting process variables
Most of the API calls require a token. The token is generated on creating a new agent.
By default, the connector read the token from the process variable with the name token
.
If you use a different variable for the token, or store the token as a connector secret, you need to adjust the authentication property of the connector.
API calls can fail due to various reasons. One reason is that the SpaceTraders API is rate limited. It fails a call if you send too many requests per second.
The SDK allows to configure the number of retries and the delay between retries.
By default, it retries the call 10 times with a delay of 1 second between retries.
API calls can fail due to various reasons, for example, network issues or invalid parameters.
The SDK allows to configure the error handling. A common use case is to throw a BPMN error if the call fails with a
specific error code (e.g. 4236
). The BPMN error can be caught by an error boundary event with the given
error code and handled in the process.
By default, the SDK throws a BPMN error if the call returns a 4xx
status code. The BPMN error code is the name to the
SpaceTrader's error code (e.g. shipNotInOrbitError
for the code 4236
). All error codes are listed
here.
In the BPMN error catch event, you can access the error data by defining an output mapping for the variables error_code
,
error_name
, and error_message
.
- Automated Quickstart process using the SDK