Skip to main content

Guide - Manage Activity

Objective​

Activity is the mechanism for either uni-directional or bi-directional communication/collaboration on specific topics between Users in your Account. There are different types of supported Activities (Notes, Documents and Action Items). All modifications to an Activity are recorded as "history", which are chronological ordered change events (ie; "audit trail"). Activities may have associated comments and uploaded documents.

Creating Activity​

Start by issuing a POST - Create to the /activity endpoint.

info

Note: if you need to add comments and/or documents to an Activity BEFORE users are notified and/or see it - then we recommend creating the Activity with the status field set to "draft". This keeps the Activity hidden from users and does not trigger notifications. While in "draft" you can then make subsequent API calls to add comments/documents. When done you can make a final API call to update the Activity by changing the status to open. At this point the Activity is now visible to users and notification logic is initiated. Further detail on this flow is described below in "Activity Status".

Attachment:​

Activities must be attached to the resource in the system they pertain to, such as a project. You must provide the attached to "type" and attached to "internal ID" in the create call, which must be a resource owned by the account internal ID you've provided.

User Assignment:​

Activities are either assigned to no users, which means they are visible to all users, or they are attached to one or more users, in which case only this set of users can view or interact with this Activity. While it is suggested that all users which are assigned to an activity have access to the underlying resource the activity is attached to, we do not enforce this.

Status:​

If an Activity is immediately ready for user consumption (ie; a "Note"), then you can create the Activity with a status of "open" or "complete" and users will have immediate access to it and notification logic will be applied.

However, if an Activity requires several API calls to prepare it (ie; add comments/documents to it) before users should be able to access it, then we suggest that you create the Activity with the status initially set to "draft". Draft Activities are hidden from users in the Incentify system and notification logic is suspended. This allows you to set comments and documents on an Activity before making it visible to users. After this setup work is done, you would then issue an update API call to set the status from "draft" to "open" (or "complete").

Notifications:​

When creating an activity, you can choose the types of notifications it should generate. The options are:

  • none - no notifications are ever sent
  • digest - any changes to the Activity are sent in an interval-based email notification
  • instant - any changes to the Activity trigger near realtime email notifications

As mentioned above, if an Activity is in status "draft" then no notifications are sent regradless of this setting.

Activity Completion Permission:​

You can configure an Activity to define who is capable of marking the Activity as complete. The options for who can mark an activity as complete are:

  • us - your internal system (ie; API calls only)
  • them - the set of users who are assigned to the Activity
  • both - "us" and "them"

Updating Activity​

You can update a number of fields on the Activity after it's creation, including subject, description, due_date, status and the set of assigned users. Things you can not change after creation of an Activity include the created_by information, the type, the attached_to information, and any of the identities or flags. This can be done by issuing a POST - Update to the /activity endpoint with the internal_activity_id.

Add Comment To Activity​

Comments can be attached to many types of resources (inculding an Activity). In this case, you would issue a POST - Create Comment with attached_to_type = "activity" and attached_to_internal_id = the ID of the activity in your internal system.

Add Document To Activity​

Documents can be attached to many types of resources (inculding an Activity). In this case, you would issue a POST - Create Document with attached_to_type = "activity" and attached_to_internal_id = the ID of the activity in your internal system.

For more general information about pushing your internal documents to Incentify, please see the Document Push/Pull Guide

Get Activity History​

For every Activity, we track a chronological history of changes made to it. There is a paginated GET - History List which you would call with either a list of project IDs or activity IDs internal to your system.

Syncing Updates to Activity​

As Users make updates to Activity on Incentify, you might want to sync those changes with your internal system. Please refer to the Syncing Changed Resources Guide to learn how you can check for changes and sync those changes with your internal system.