WorkSharing API

Native issue-level integrations provide API for interaction with the tool's HTTP API, getting entity shares, sharing entities, removing entity share (unlink), etc.

Use getService function to get the WorkSharingAPI:

context.getService('workSharing/v2')

This function returns object with WorkSharingV2Api interface. It has the following definition:

export interface WorkSharingV2Api {
  /**
   * Returns an HTTP proxy object for a specified tool
   * @param tool Tool descriptor.
   * @return Http client for provided tool descriptor
   */
  getProxy(tool: { id: string; type: 'Targetprocess' | 'Jira' | 'Azure' | string }): HttpApi

  /**
   * Returns an array of entities given entity is syncing with
   * @param entity.
   * @return Shares for the provided entity.
   */
  getEntityShares(entity: EntityRef): Promise<{
    sourceId: string
    sourceType: string
    tool: ToolRef
  }[]>

  /**
   * Shares entity to a specified tool with specified mappings and overrides
   * @param entity.
   * @return EntityRef of a synced entity in another tool.
   */
  shareEntity(shareCommand: {
    sourceEntity: {
      sourceId: string,
      sourceType: string,
      tool: ToolRef
    },
    targetId?: string | undefined
    /// Using profile's target tool if not specified
    targetTool?: ToolRef
    mappingId: string
    targetOverrides?: any | undefined
    stateTransfer?: StateTransferPayload | undefined
  }): Promise<EntityRef[]>

  /**
   * Shares entity to a specified tool with specified mappings and overrides
   * @param entity.
   * @return EntityRef of a synced entity in another tool.
   */
  shareEntities(shareCommands: {
    sourceEntity: {
      sourceId: string,
      sourceType: string,
      tool: ToolRef
    },
    targetId?: string | undefined
    /// Using profile's target tool if not specified
    targetTool?: ToolRef
    mappingId: string
    targetOverrides?: any | undefined
    stateTransfer?: StateTransferPayload | undefined
  }[]): Promise<ShareEntityResponse[]>

  /**
   * Remove entity share (unlink)
   * @param entity.
   */
  deleteEntitySharing(entity: {
    sourceId: string,
    sourceType: string,
    tool: ToolRef
  } | DeleteEntitySharePayload): Promise<void>

  /**
   * Get work sharing integration profiles for this account
   * @return Successful response
   */
  getProfiles(): Promise<Profile[]>
}

Full definition of types can be found at https://{{account_name}}.tpondemand.com/svc/js-executor/types

getProxy

The function receives ToolRef and returns HttpApi object. You can use this object to perform get/post/put/patch/delete requests to the profile's tool HTTP API. The following example shows how this function can be used to interact with Jira API using getProxy

// create workSharing service
const workSharing = context.getService('workSharing/v2')
// fetch integration profiles for account. For example, the first profile has a Jira type. 
const jiraProfile = (await workSharing.getProfiles())[0]
// create proxy to interact with Jira API
const jiraApi = workSharing.getProxy(jiraProfile.targetTool)

// fetch issue from Jira
const issue = await jiraApi.getAsync('/rest/api/2/issue/TEST-52')

getEntityShares

Returns array of all entities given entity is syncing with. The following example shows how this API can be used in Automation Rules:

const service = context.getService('workSharing/v2')
const shares = service.getEntityShares({
  sourceType: args.ResourceType,
  sourceId: args.ResourceId.toString(),
  tool: {
    id: args.Account,
    type: 'Targetprocess'
  }
})

shareEntity/shareEntities

These functions can be used to share a single entity or array of entities to the integration profile's target/source tool or link to an existing item.

const sync = context.getService("workSharing/v2")

const entity = {
  sourceType: args.Current.ResourceType,
  sourceId: `${args.Current.Id}`,
  tool: {
    type: 'Targetprocess',
    id: args.Account
  }
}

const profiles = await sync.getProfiles()

const currentProfile = profiles[0]
const mappingId = currentProfile.mappings[0].id

await sync.shareEntity({
  sourceEntity: entity,
  mappingId,
  stateTransfer: {
    kind: "source"
  },
  targetTool: currentProfile.targetTool
})

This function is not expected to be used in JavaScript routings and field mappings. It may lead to situations when an entity will be shared with another tool more than 1 time or loops in your scripts

deleteEntitySharing

Unlink - removes entity share for the given entity. Example:

const service = context.getService('workSharing/v2')
const shares = service.deleteEntitySharing({
  sourceType: args.ResourceType,
  sourceId: args.ResourceId.toString(),
  tool: {
    id: args.Account,
    type: 'Targetprocess'
  }
})

getProfiles

Returns an array of issue level integration profiles for the current account

const sync = context.getService("workSharing/v2")
const profiles = await sync.getProfiles()