CRM-2 Tags API

From Opentaps Wiki

Jump to: navigation, search

Tags are a way to group your activities and tasks and link them to the outside world. The tags in opentaps crm2 have a tag name, which is the description, plus a URL and keywords. The URL can be used to link tagged activities to outside data, such as linking emails and notes to a sales order in another system. The keywords can be used to search for activities which may be related to the tag. For example, we can use it to search for emails which may be related to an invoice.

Tags are inherited in the following way:

  1. When an activity is tagged, a new task created from the activity will have the same tags
  2. When a task is tagged, any activity created from the task will be tagged as well.
  3. When an existing activity is linked to an existing task, the tags from that task will be inherited by the activity. However, the activity may have existing tags, and those will still be there as well -- they are not erased when an activity is transferred from one task to another.

Tags

A tag can store the following data:

  • tagId - unique identifier
  • tag name - descriptive text of the tag
  • an optional URL link which can be used to link to an outside system, such as the order ID or party ID of a legacy ERP or CRM system.
  • keywords which can be used for searching similar documents

Tag names are case insensitive, so the tags opentaps, OPENTAPs, and OpenTaps would all be considered the same.

Tags have a hierarchy based on their name. If a tag has two colons (::) in its name, then the first part before the :: is the parent tag of all tags which contains it. For example, Sales Order:: would be the parent tag of Sales Order::12345, Sales Order::45678 In the user interface, the parent tags are shown in the Tags tab, and when you click on a parent tag, the child tags are shown.

API

Endpoint: https://crm2.opentaps.com/tag

POST: Create a new tag

Parameters:

  • clientDomain
  • authToken
  • tagName
  • tagUrl
  • tagKeywords

Returns

  • tagId: unique identifier of your tag

If the same tagName (case insensitive) already exists, then the operation would return an error.

PUT: Update an existing tag using the unique tagId

Parameters:

  • clientDomain
  • authToken
  • tagId

DELETE: Delete an existing tag using the unique tagId

Parameters:

  • clientDomain
  • authToken
  • tagId

GET: Search for existing tags which contain your tag name (case insensitive)

Parameters:

  • clientDomain
  • authToken
  • tagName

Returns

  • List of tags, including tagId, tagName, tagUrl, tagKeywords for each tag
Relating Tags to Tasks and Activities

A tag can be added to any task or activity.

If you append the fields tagName, tagUrl, tagKeywords, parentTagId to any POST API call to create an activity or task, crm2 will check if the tagName already exists. If so, the activity or task will be associated with your tag. In that case, the URL and keywords will be ignored. If the tag name is not found, it will automatically create a new tag with the name, URL, and keywords and associate it with your task or activity.

You can get all the activities and tasks related to a tag with the API call to https://crm2.opentaps.com/tagActivities

GET: Get all activities and tasks related to a task

Parameters:

  • clientDomain
  • authToken
  • tagId

Returns

  • List of activities and tasks related to the tag

GET: Get all the tags related to an activity

Parameters:

  • clientDomain
  • authToken
  • activityId

Returns

  • List of tags, including all their tagId, tagName, tagUrl, tagKeywords, related to the activity

POST: Add a tag to an activity

Parameters:

  • clientDomain
  • authToken
  • activityId
  • tagId

DELETE: Delete a tag from an activity

Parameters:

  • clientDomain
  • authToken
  • activityId
  • tagId


© Open Source Strategies, Inc. Development of this documentation site is sponsored by Open Source Strategies, Inc.
Help support opentaps with a subscription to this documentation site.