Mapping Jira statuses to Jira Align process steps

Summary

Use this article to map Jira issue statuses to Jira Align process steps via the Jira Align REST API, so Jira status changes automatically update the corresponding process step.

Jira State → Jira Align Process Step Mapping UI

Purpose: When a Jira issue status changes, the corresponding Jira Align process step is updated.

See the parent page for full mapping details: Mapping States, Process Steps, and Statuses between Align and Jira via API

Solution

Retrieve process step mappings

Retrieve all Jira -> Align process step mappings for a connector.

Endpoint: GET /Connectors/{connectorId}/mappings/process-steps

Query parameters:

• ProjectKey (optional):

  • Omit or set to null: Returns company-managed project mappings only

  • Set to project key: Returns team-managed project mappings for that specific project

• WorkItemTypeId (optional): Filter by work item type ID

• $top, $skip, $filter, $orderby (OData query options)

Example request for company-managed project:

Example request for team-managed project:

Example response:

Retrieve single process step mapping

Retrieve a specific process step mapping by ID.

Endpoint: GET /Connectors/{connectorId}/mappings/process-steps/{mappingId}

Example request:

GET /align/api/2/Connectors/123/mappings/process-steps/20Authorization: Bearer {your-api-token}

Create a process step mapping

Create a new Jira -> Align process step mapping.

Note: WorkItemTypeId is automatically determined based on processStepId

Endpoint: POST /Connectors/{connectorId}/mappings/process-steps

Request body:

Example request for company-managed project:

Example request for team-managed project:

Note: Project key is automatically determined based on JiraStatusId

Example response (201 Created):

Notes:

• You can map more than one Jira status to use the same Align process step

• We recommend that your process steps match your Jira states, making such a configuration unnecessary

Update a process step mapping

Update an existing process step mapping. Only the processStepId field is mutable for Jira → Align process step mappings.

Endpoint: PUT /Connectors/{connectorId}/mappings/process-steps/{mappingId}

Request body:

{ "processStepId": 6 // Only mutable field - required}

Note: The following fields are not mutable and will be ignored if provided:

• workItemTypeId

• jiraStatusId

• projectKey

• connectorId

• mappingId

Example request:

Example response:

• 204 No Content on successDelete Process Step Mapping

Delete a process step mapping

Endpoint: DELETE /Connectors/{connectorId}/mappings/process-steps/{mappingId}

Example request:

DELETE /align/api/2/Connectors/123/mappings/process-steps/20Authorization: Bearer {your-api-token}

Example response:

• 204 No Content on success, 404 Not Found if mapping doesn't exist