API

Ceptah Bridge can be controlled from VBA in MS Project or from an external application using its API.

To get access to the API, do the following:

1. Open the VBA editor, select Tools > References... and add a reference to MspJiraBridge_Api.

2. Use the code below to retrieve the root object of the API.

   Dim api As ICeptahBridge
   Set api = Application.COMAddIns.Item("MspJiraBridge.AddinModule").Object

The API exposes the following methods:

• Function GetBlankSettings() As ProjectSettings

  Returns a blank settings object.

• Sub ExportSettings(settings As ProjectSettings, fileName As String)

  Saves settings in an XML file

• Function ImportSettings(fileName As String) As ProjectSettings

  Loads settings from an XML file

• Function GetSettings([project As Project]) As ProjectSettings

  Retrieves settings from a project. If project is not provided, the settings are read from the active project.

• Sub SetSettings(settings As ProjectSettings, [project As Project])

  Replaces settings in a project. If project is not provided, the active project is updated.

• Function Synchronize(mode As TaskEnumerationMode, [settings As ProjectSettings[, [project As Project]]) As Boolean

  Starts synchronisation.

  Mode can have the following values.

  • Const TaskEnumerationMode_All = 0 - synchronise all tasks in the project. This is an equivalent of the Synchronise command in the menu.

  • Const TaskEnumerationMode_Selected = 1 - synchronise only selected tasks. This is an equivalent of the Synchronise Selected command in the menu.

  • Const TaskEnumerationMode_Linked = 2 - synchronise only linked (published) tasks. This is an equivalent of the Synchronise Existing command in the menu.

  If settings are not provided, the settings of the synchronised project are used.

  If a project is not provided, the active project is processed.

• Function Import([settings As ProjectSettings, [enterFilter As Boolean = True[, [project As Project]]]) As Boolean

  Starts import.

  If settings are not provided, the settings of the updated project are used.

  If "enterFilter" is True or omitted, the system opens the Import Dialog and allows the user to enter a filter for the issues to be imported. Otherwise, if "enterFilter" is False, import starts immediately using the filter specified in the settings object.

  If a project is not provided, the active project is processed.

• Function SynchronizeSilent(settings As ProjectSettings, project As Project, indexes() As Long) As Boolean

  Silently compares issues with tasks and applies changes.

  The settings and the project must be explicitly provided.

  indexes - 1-based indexes of the tasks to synchronise.

• Function ImportSilent(settings As ProjectSettings, project As Project) As Boolean

  Silently imports issues using the filter from the settings and applies changes.

  The settings and the project must be explicitly provided.

The properties and methods of the ProjectSettings object can be inspected in the Object Browser. To configure collections, use SetXXX methods. To access collections, use GetXXX methods. To create elements for the collections, use the CreateXXX methods. For instance, to read links call GetLinks ProjectSettings.Mappings.GetLinks, to update links, call ProjectSettings.Mappings.SetLinks, and to create an entry for the collection, call CreateLink.

The following example creates a new set of settings from scratch, imports all issues from a JIRA project into the active project and then saves the settings in a file. The project does not need to have any mappings configured.

Sub Import()
  Dim api As ICeptahBridge
  Set api = Application.COMAddIns.Item("MspJiraBridge.AddinModule").Object
  
  Dim settings As ProjectSettings
  Set settings = api.GetBlankSettings()
  
  settings.Mappings.IssueKeyField = "Text10"
  settings.Mappings.SummaryMappingMethod = SummaryMappingMethod_Name
  settings.Mappings.DefaultProjectKey = "CTP"
  settings.Mappings.DefaultPriority = "Intermediate"
  settings.Mappings.DefaultIssueType = "Task"
  
  Dim statuses(0) As String
  statuses(0) = "In Progress"
  
  Dim changeLog(0) As ChangeLogEntryMapping
  Set changeLog(0) = settings.Mappings.CreateChangeLogEntry()
  changeLog(0).Field = "status"
  changeLog(0).SetTo statuses
  changeLog(0).CreatedTaskField = "Start"
  changeLog(0).IsFirst = True
  changeLog(0).AsDate = True
  
  settings.Mappings.SetChangeLog changeLog
  
  settings.ImportMode = ImportListMode_Project
  settings.ImportProjectKey = "CTP"
  
  api.Import settings, False
  
  api.ExportSettings settings, "c:\temp\Settings.xml"
End Sub