Jira Service Management (JSM)

Custom Ocean integration

This integration was created using the custom Ocean integration builder.
Please note that:

1. This integration will not be listed in the Data sources page of your Port application, and must be installed manually using the instructions on this page.
2. This integration will not create components (e.g. blueprints, mapping, etc.) in your portal automatically, you will need to create them manually using the instructions on this page.

Port's Jira Service Management integration allows you to model JSM service desk resources in your software catalog and ingest data using the Ocean Custom Integration framework. This guide focuses on three Service Desk REST API endpoints: listing service desks, customer requests, and organizations.

Supported resources

The integration can ingest the following resources:

• service-desk: service desks from GET /rest/servicedeskapi/servicedesk.
• customer-request: customer requests from GET /rest/servicedeskapi/request.
• organization: organizations from GET /rest/servicedeskapi/organization.

You can reference any fields returned by these endpoints in the mapping configuration.

Prerequisites

You need:

• Jira Service Management Cloud on Atlassian Cloud. Your site URL follows the form https://your-domain.atlassian.net.
• An Atlassian API token for basic authentication (recommended for integrations).
• An Atlassian user that can read service desks, customer requests, and organizations in JSM.

To create an API token:

1. Log in at Atlassian account security - API tokens.
2. Choose whether you want a scoped token or an all-purpose token. Either works with this integration when you set base URL the way Atlassian expects for that token type.
   • Create API token with scopes if you want a restricted token and you select only the scopes for the actions you need. Choose read scopes that cover the Service Desk endpoints you sync. Atlassian lists the permission names on each operation in the Service Desk REST API reference (they appear as OAuth scopes in the docs). Use Atlassian's gateway base URL: https://api.atlassian.com/ex/jira/{cloudId}. Find your Cloud ID in Retrieve my Atlassian sites Cloud ID.
   • Create API token if you want an all-purpose token with the same broad access as your account (no per-action scope picker). Use your Jira site base URL: https://YOUR_DOMAIN.atlassian.net, as in the Installation examples on this page.
3. Name the token (for example Port Ocean), click Create, then copy it and store it securely. You cannot retrieve it later.

Basic authentication for Jira Cloud: use your Atlassian account email address as the username and the API token as the password in the integration secrets (see the Installation section on this page).

Keep credentials secure

Never commit credentials to source control. Store them only in secrets for your Ocean deployment or in Port-hosted integration settings.

Installation

Choose one of the following installation methods:

Hosted by Port

Set up in Port

1. Go to the custom data source page and open the Ocean custom integration form.
2. Configure:
   • Identifier: my-ocean-jsm-integration.
   • Base URL: https://YOUR_DOMAIN.atlassian.net (your Jira Cloud site).
   • Authentication type: basic.
   • Username: your Atlassian account email address.
   • Password: your Jira API token.
3. Expand Advanced configuration and set:
   • Pagination type: next_link.
   • Next link path: _links.next.
   • Page size: 50 or 100 (maps to Atlassian limit on first requests).
4. Click Save & install.

Continue with the mappings

After the integration is installed, continue to Configuration on this page and add the resource mappings.

Helm

Prerequisites

• A Kubernetes cluster - the integration's container chart will be deployed to this cluster.

• kubectl and helm must be installed on your machine. Your kubectl CLI must be connected to the Kubernetes cluster where you plan to install the integration.

Installation

1. Add Port's Helm repo and install the Ocean Custom Integration:

Replace placeholders

Replace placeholders for Port credentials (YOUR_PORT_CLIENT_ID, YOUR_PORT_CLIENT_SECRET), your YOUR_ATLASSIAN_EMAIL, YOUR_JIRA_API_TOKEN, and your site URL https://YOUR_DOMAIN.atlassian.net.

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install my-ocean-jsm-integration port-labs/port-ocean \
  --set port.clientId="YOUR_PORT_CLIENT_ID" \
  --set port.clientSecret="YOUR_PORT_CLIENT_SECRET" \
  --set port.baseUrl="https://api.port.io" \
  --set initializePortResources=true \
  --set scheduledResyncInterval=60 \
  --set integration.identifier="my-ocean-jsm-integration" \
  --set integration.type="custom" \
  --set integration.eventListener.type="POLLING" \
  --set integration.config.baseUrl="https://YOUR_DOMAIN.atlassian.net" \
  --set integration.config.authType="basic" \
  --set integration.secrets.username="YOUR_ATLASSIAN_EMAIL" \
  --set integration.secrets.password="YOUR_JIRA_API_TOKEN" \
  --set integration.config.paginationType="link" \
  --set integration.config.nextLinkPath="_links.next" \
  --set integration.config.pageSize=50

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

Configuration parameters

Parameter	Description	Example	Required
port.clientId	Your Port client ID		✅
port.clientSecret	Your Port client secret		✅
port.baseUrl	Your Port API URL (https://api.port.io for EU, https://api.us.port.io for US)		✅
integration.config.baseUrl	Jira Cloud site root (no /rest/... suffix)	https://your-domain.atlassian.net	✅
integration.config.authType	Use basic with email + API token	basic	✅
integration.secrets.username	Atlassian account email	you@company.com	✅
integration.secrets.password	Jira Cloud API token		✅
integration.config.paginationType	JSM returns next page URLs in JSON; use link	link	✅
integration.config.nextLinkPath	Path to the next page URL in each response	_links.next	✅
integration.config.pageSize	Page size for the first request (limit query param)	50	❌
integration.eventListener.type	Event listener type	POLLING	✅
integration.type	Must be custom for Ocean Custom Integration	custom	✅
integration.identifier	Unique integration instance ID	my-ocean-jsm-integration	✅
scheduledResyncInterval	Minutes between resyncs	60	❌
initializePortResources	Create default blueprints/mapping on first run	true	❌
sendRawDataExamples	Send raw API examples to Port for mapping tests	true	❌

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Docker

To run the integration using Docker for a one-time sync:

Replace placeholders

Replace Port credentials, YOUR_ATLASSIAN_EMAIL, YOUR_JIRA_API_TOKEN, and YOUR_DOMAIN.

docker run -i --rm --platform=linux/amd64 \
  -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \
  -e OCEAN__INITIALIZE_PORT_RESOURCES=true \
  -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \
  -e OCEAN__INTEGRATION__CONFIG__BASE_URL="https://YOUR_DOMAIN.atlassian.net" \
  -e OCEAN__INTEGRATION__CONFIG__AUTH_TYPE="basic" \
  -e OCEAN__INTEGRATION__SECRETS__USERNAME="YOUR_ATLASSIAN_EMAIL" \
  -e OCEAN__INTEGRATION__SECRETS__PASSWORD="YOUR_JIRA_API_TOKEN" \
  -e OCEAN__INTEGRATION__CONFIG__PAGINATION_TYPE="link" \
  -e OCEAN__INTEGRATION__CONFIG__NEXT_LINK_PATH="_links.next" \
  -e OCEAN__INTEGRATION__CONFIG__PAGE_SIZE="50" \
  -e OCEAN__PORT__CLIENT_ID="YOUR_PORT_CLIENT_ID" \
  -e OCEAN__PORT__CLIENT_SECRET="YOUR_PORT_CLIENT_SECRET" \
  -e OCEAN__PORT__BASE_URL="https://api.port.io" \
  ghcr.io/port-labs/port-ocean-custom:latest

Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

• EU (app.port.io) → https://api.port.io
• US (app.us.port.io) → https://api.us.port.io

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Set up data model

Create blueprints before syncing. Create jsmServiceDesk before jsmCustomerRequest, because the customer request blueprint relates requests to a service desk.

To create the blueprints:

1. Go to your Builder page.

2. Click + Blueprint.

3. Click the {...} Edit JSON button in the top right corner of the form.

4. Copy and paste each blueprint JSON from the sections below. Recommended order: service desk, then customer request, then organization. Create the service desk blueprint before the customer request blueprint because of the relation.

   JSM Service desk blueprint (click to expand)

   {
     "identifier": "jsmServiceDesk",
     "title": "JSM Service desk",
     "icon": "Service",
     "description": "A Jira Service Management service desk",
     "schema": {
       "properties": {
         "projectId": {
           "type": "string",
           "title": "Project ID"
         },
         "projectKey": {
           "type": "string",
           "title": "Project key"
         },
         "projectName": {
           "type": "string",
           "title": "Project name"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

   JSM Customer request blueprint (click to expand)

   {
     "identifier": "jsmCustomerRequest",
     "title": "JSM Customer request",
     "icon": "Ticket",
     "description": "A customer request in Jira Service Management",
     "schema": {
       "properties": {
         "issueKey": {
           "type": "string",
           "title": "Issue key"
         },
         "summary": {
           "type": "string",
           "title": "Summary"
         },
         "status": {
           "type": "string",
           "title": "Status"
         },
         "createdAt": {
           "type": "string",
           "title": "Created at (ISO-8601)"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {
       "serviceDesk": {
         "title": "Service desk",
         "target": "jsmServiceDesk",
         "required": false,
         "many": false
       }
     }
   }

   JSM Organization blueprint (click to expand)

   {
     "identifier": "jsmOrganization",
     "title": "JSM Organization",
     "icon": "Users",
     "description": "A JSM organization",
     "schema": {
       "properties": {
         "name": {
           "type": "string",
           "title": "Name"
         },
         "scimManaged": {
           "type": "boolean",
           "title": "SCIM managed"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {}
   }

5. Click Save after creating each blueprint.

Configuration

Define which API paths sync into Port using JQ expressions. Map each resource:

• kind: appended to baseUrl. Use the /rest/servicedeskapi/... paths below.
• selector.data_path: .values picks the entity array inside JSM paging responses.

For how Ocean combines baseUrl and pagination, see How it works.

JSM response shape

Paged list responses follow:

{
  "size": 3,
  "start": 0,
  "limit": 50,
  "isLastPage": false,
  "_links": {
    "next": "https://YOUR_DOMAIN.atlassian.net/rest/servicedeskapi/..."
  },
  "values": [ {} ]
}

Use data_path: ".values" for each kind that returns this envelope.

To configure:

1. Go to your data sources page.

2. Find your Jira Service Management integration in the list.

3. Click on the integration to open the mapping editor.

4. Add the resource mapping configurations below (sync service desks before customer requests if you use the service desk relation on requests).

   Service desks (click to expand)

   API: GET /rest/servicedeskapi/servicedesk

   resources:
     - kind: /rest/servicedeskapi/servicedesk
       selector:
         query: "true"
         data_path: ".values"
       port:
         entity:
           mappings:
             identifier: .id | tostring
             title: .projectName // .projectKey // .id
             blueprint: '"jsmServiceDesk"'
             properties:
               projectId: .projectId | tostring
               projectKey: .projectKey
               projectName: .projectName

   Customer requests (click to expand)

   API: GET /rest/servicedeskapi/request

   resources:
     - kind: /rest/servicedeskapi/request
       selector:
         query: "true"
         data_path: ".values"
       port:
         entity:
           mappings:
             identifier: .issueId | tostring
             title: .summary // .issueKey
             blueprint: '"jsmCustomerRequest"'
             properties:
               issueKey: .issueKey
               summary: .summary
               status: .currentStatus.status
               createdAt: .createdDate.iso8601
             relations:
               serviceDesk: .serviceDeskId | tostring

   Organizations (click to expand)

   API: GET /rest/servicedeskapi/organization

   resources:
     - kind: /rest/servicedeskapi/organization
       selector:
         query: "true"
         data_path: ".values"
       port:
         entity:
           mappings:
             identifier: .id | tostring
             title: .name
             blueprint: '"jsmOrganization"'
             properties:
               name: .name
               scimManaged: .scimManaged

5. Click Save to apply the mapping.

Customization

Use the interactive builder to probe live JSM responses, validate JQ, and generate blueprints before you lock in mappings.

Additional resources

• Jira Service Management Cloud REST API (authentication, scopes, pagination).
• Ocean Custom Integration overview
• Ocean Custom Integration configuration (mapping options and pagination).