sdk

SpaceTraders SDK for Camunda

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

Install

Via Camunda Marketplace

1. Find the SDK in the Camunda Marketplace
2. Click the button "For SAAS". You will be forwarded to the Camunda Web Modeler.
3. On the download modal, select a project to publish the connector to.

The connector is now available within the select project. 🚀

Manually for Web Modeler

1. Open the Camunda Web Modeler
2. Open a project or create a new one.
3. Upload the connector template spacetraders.json (see how)
4. Publish the connector template (see how)

Usage

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 connector to your process

1. Add a new task to your process
2. Select the SpaceTraders connector as the task type (e.g. SpaceTraders)
3. Select the category in the properties (e.g. Fleet)
4. Select the operation (e.g. getMyShip - Get Ship)
5. Fill the required parameters (e.g. shipSymbol)
6. Optionally, adjust the result expression to customize the resulting process variables

Authentication

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 Retries

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 Error handling

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.

Examples

• Automated Quickstart process using the SDK