Scenario workflow
When working with Wogeez scenarios, following a clear workflow helps streamline your integration and deployment process. You typically start by generating a scenario from a provided skeleton or using existing templates. Next, you customize this scenario by implementing your specific business logic, visual elements, and content. Once customized, you upload the scenario onto the Wogeez platform using a dedicated API. Finally, you deploy your scenario to your kiosks or connected devices through the platform's management tools. The sections below detail each step and corresponding APIs.
Workflow
sequenceDiagram
autonumber
API GET /resources/scenarios/skeleton.zip->>scenario.zip: Create skeleton scenario archive
scenario.zip->>scenario.zip: Unzip
scenario.zip->>scenario.zip: Customize scenario.json, thumbnails and assets
scenario.zip->>scenario.zip: Zip
scenario.zip->>API POST /resources/scenarios: Upload scenario.zip
API POST /resources/scenarios->>API POST /resources/scenarios: Server check scenario.zip
API POST /resources/scenarios->>API POST /resources/deployments: Deploy scenarios on a kiosk- Generate: Create scenarios via API or your scenario library.
- Customize: Adapt the scenario (business logic, visuals, content).
- Upload: Import your scenario using the dedicated API.
- Deploy: Push the scenario to kiosks/devices through the Wogeez platform.
Generate
This step involves creating an initial scenario template (also called a skeleton). The generated ZIP archive contains foundational files necessary to start building your custom scenario. Quickly provides the basic file structure (scenario.json, resources directory, etc.) required by Wogeez for scenarios.
Make a GET request to :
curl -X 'GET' \
'https://api-v2.wogeez.com/companies/{id}/resources/scenarios/skeleton.zip?version={version}' \
-H 'accept: application/zip' \
-H 'Authorization: Bearer your-jwt-token'
Parameters
- id: The company identifier (mandatory)
- version: The scenario package version (optional, default 1.0.0)
API response :
Upon successful execution, the API returns a ZIP archive containing a generic scenario skeleton. This ZIP includes:
Customize
For the customization step, refer directly to the official scenario package documentation, which explains in detail how to adapt the scenario structure (scenario.json), integrate your specific business logic, manage visuals, and ensure compatibility with Wogeez standards.
Upload
After customizing your scenario, upload the complete ZIP archive to Wogeez via a dedicated API endpoint.
curl -X POST 'https://api.wogeez.com/companies/{id}/resources/scenarios' \
-H 'Authorization: Bearer your-jwt-token' \
-F '[email protected];type=application/zip'
Parameters
- id: The company identifier (mandatory)
- payload: ZIP file containing your customized scenario (scenario.json and resources).
API response :
- 201 Created: Successfully uploaded. The scenario is correctly stored on the platform and is ready for deployment.
- 413 Insufficient Storage: The upload cannot be processed due to insufficient storage available on the server for your company.
- 422 Invalid Scenario: Your scenario archive is invalid or incorrectly structured. Ensure your scenario.json complies with required standards and includes all necessary resources.
Deploy a scenario
After generating, customizing, and uploading your scenario to the Wogeez platform, the final step is deploying the scenario to your kiosks or connected devices.
This step is executed via a dedicated API, allowing precise control over where and how your scenarios are deployed. You can simultaneously deploy multiple scenarios and different versions of the same scenario across various devices.
curl -X POST 'https://api-v2.wogeez.com/companies/{id}/resources/deployments' \
-H 'accept: application/zip' \
-H 'Authorization: Bearer your-jwt-token' \
-H 'Content-Type: application/json' \
-d '{
"requests": [
{
"target": {
"type": "DEVICE",
"id": "device-id",
"subId": null
},
"what": {
"type": "SCENARIO",
"id": "scenario-id",
"subId": "scenario-version-id"
},
"action": "DEPLOY"
}
],
"note": "A simple note to explain the reason for deployment"
}'
To perform a deployment or undeployment, send a POST request to the following API. To undeploy a scenario instead of deploying it, simply set the action field to UNDEPLOY.
Parameters
- id: Your company identifier (required).
- requests: List of deployment requests targeting specific devices and scenarios to deploy (required).
- requests.target : Information about the target device (type, id).
- requests.what : Information about the scenario to deploy (type, id, subId corresponding to the specific scenario version).
- requests.action : Optional note explaining the reason or context for deployment.
API Response
The API responds with an object containing detailed deployment status information:
{
"items": [
{
"id": "deployment-id",
"target": {
"type": "DEVICE",
"id": "device-id",
"subId": null
},
"what": {
"type": "SCENARIO",
"id": "scenario-id",
"subId": "scenario-version-id"
},
"action": "DEPLOY",
"state": "SUCCESS",
"cause": null
}
]
}
Possible States
- SUCCESS: The scenario was successfully deployed.
- FAILURE: The deployment failed. Check the "cause" field for further details.
Possible values for "cause":
- NONE: No specific cause indicated.
- TARGET_NOT_FOUND: The target device does not exist.
- WHAT_NOT_FOUND: The scenario or scenario version does not exist.
- ALREADY_DEPLOYED: The scenario is already deployed on the device.
- ALREADY_UNDEPLOYED: The scenario has already been removed from the device.
- NOT_IMPLEMENTED: The requested function is not implemented.
Retrieve Active Deployments
You can retrieve currently active deployments (only those with SUCCESS status) using the following web services:
- For a specific device (kiosk): GET resources/{id-kiosk}/deployments
- For all devices (kiosks): GET resources/DEVICE/deployments