Under active development
OCAPI and Jobs support is under active development and will be reworked soon. This page describes how it works in the current release
OCAPI is optional. Turn it on for a connection to activate code versions from B2C Explorer and to run jobs from the B2C OCAPI tool window at the bottom of the IDE. Uploads, deploys, B2C Explorer and the debugger use the connection's account instead
Set up OCAPI
A connection needs an API client, permission for it on the instance and its own OCAPI settings. With OCAPI off, the Jobs tab can't run or find jobs
Add an API client
Add it on the API Clients tab of B2C Credentials. On sandboxes and test systems you can start with the built-in OOTB Test Creds client
Allow the client on the instance
Grant it the Data API resources in Business Manager setup
Turn it on for the connection
On the OCAPI tab of Connections Settings, check Use OCAPI, pick the Credentials and the Version, then click Test OCAPI Connection. The tab toolbar of B2C OCAPI changes the same three settings in place
Business Manager setup
- In Business Manager, go to Administration › Site Development › Open Commerce API Settings
- Select Data API and Global
- Add a client entry like the one below, with your client ID and an OCAPI version your instance supports, then save
{
"_v": "23.2",
"clients": [
{
"client_id": "<your-client-id>",
"resources": [
{
"resource_id": "/code_versions/*",
"methods": ["patch"],
"read_attributes": "(**)",
"write_attributes": "(**)"
},
{
"resource_id": "/jobs/*/executions",
"methods": ["post"],
"read_attributes": "(**)",
"write_attributes": "(**)"
},
{
"resource_id": "/jobs/*/executions/*",
"methods": ["get"],
"read_attributes": "(**)",
"write_attributes": "(**)"
}
]
}
]
}These cover the plugin's three calls: activate a code version, start a job and read its status. If other clients are listed, add your entry to the existing clients array
No WebDAV client permissions needed
Guides for command line tools often add WebDAV Client Permissions for the API client. Intellij SFCC doesn't need them, its WebDAV requests use the connection's account
Activate a code version
With OCAPI on, right-click a version under Code versions in B2C Explorer
| Item | What it does |
|---|---|
| Activate and Select Code Version | Activates the version on the instance and selects it for uploads and deploys |
| Activate Code Version | Activates the version on the instance only |
| Select Code Version | Selects it for uploads and deploys only. Works without OCAPI |
Activating runs in the background ("Activating version3 Code Version") and moves "[Active on instance]" to that version. The selected version has the code version icon and shows on the main toolbar, see Deploy Code
B2C OCAPI tool window
The window has one tab per instance, in the instance's colour with a line of it under the tab toolbar, see Instance colours. With no tab yet it shows "No OCAPI Configurations"
- Click + (New OCAPI Connection), choose the Instance and click Create. It takes a connection, a group shows "Group is not allowed. Please select connection."
- The tab toolbar shows the connection's OCAPI settings and changes them in place
| Toolbar | What it does |
|---|---|
| Use OCAPI: | Same as Use OCAPI in Connections Settings. With it off, the Jobs actions are disabled |
| Instance: | The connection the tab sends requests to, plus Edit Connection to open its settings |
| Credentials: | The API client, from the clients in B2C Credentials |
| Version: | The OCAPI version |
Closing a tab asks before it removes that OCAPI connection from the window
Jobs list
The Jobs tab lists job IDs with their status, sorted by ID and saved with the tab
| Action | What it does |
|---|---|
| Find Jobs in jobs.xml | Adds the job-id of every job in the project's jobs.xml files that isn't listed yet |
| Add Job | Adds one job by ID ("Enter Job ID") |
| Remove Job | Removes the selected jobs from the list after a confirmation. It doesn't touch the instance, and Find Jobs in jobs.xml adds jobs from jobs.xml again |
Type while the table has focus to jump to a job ID
Run jobs
Select one or more jobs, then click Run Job or right-click a row
Run Job starts the selected jobs over OCAPI. Its name follows the selection, for example "Run ImportInventory Job" or "Run 2 Jobs". The row menu has the same Run and Remove actions
Status starts as PENDING, then shows the status of the run on the instance, such as RUNNING, OK or ERROR. It refreshes every 2 seconds until the run ends. A pending or running job can't be started again
Troubleshooting
Failed requests show a balloon at the bottom right of the IDE, and the job's Status shows how the run ended
| Message | What to do |
|---|---|
| OCAPI Not Enabled, "Please check your connection and OCAPI settings." | Turn on Use OCAPI, select the credentials and the version, and test the connection. Edit Connection in the balloon opens its settings |
| OCAPI Auth Failed | The client ID or secret is wrong, or the client is not allowed on this instance |
| OCAPI Error with a message from the server | Usually missing permissions. The balloon's Edit Data API opens the Business Manager page from Business Manager setup |
| Running ID Job Error, status NOT_FOUND | The instance has no job with that ID. Check the ID, or remove it and use Find Jobs in jobs.xml |
| Running ID Job Error, status ERROR | The instance refused the run. The balloon shows the server's reason, often a permission missing from Business Manager setup |
| Running Job Error, "Unknown error occurred while running" the job | The request got no OCAPI response. Check the connection and click Test OCAPI Connection in Connections Settings |
| Run Job is disabled | OCAPI is off for the tab, nothing is selected, or a selected job is pending or running |