WorkSharing API

Edit online

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: ___PROTECTED_5___,
  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()