Interface Api

Api accessible in all plugin scripts

interface Api {
    datamodel: DataModel;
    http: Http;
    metamodel: MetamodelApi;
    survey: SurveyApi;
    user: UserApi;
    userGroup: UserGroupApi;
    createDate(milliseconds: number): ApiDate;
    createDate(dateValue: string): ApiDate;
    createDate(
        year: number,
        month: number,
        day: number,
        hour: number,
        minutes: number,
        seconds: number,
        milliseconds: number,
    ): ApiDate;
    getHistoryForBuildingBlock(
        buildingBlockId: number,
        typePersistentName: BuildingBlockType,
    ): BBChange[];
    getHistoryForType(typePersistentName: BuildingBlockType): BBTHistory[];
    getPropertyInfo(
        buildingBlockType: BuildingBlockType,
        property: string,
    ): PropertyInfo;
    printLog(message: string): void;
    registerExecution(yourFunction: () => void): void;
    rejectChanges(message?: string): never;
    sendEmail(recipient: string, subject: string, content: string): -1 | 1;
    subscribeFor(
        buildingBlockType: BuildingBlockType,
        yourFunction: SubscriptionCb,
    ): void;
}

Properties

datamodel http metamodel survey user userGroup

Methods

createDate getHistoryForBuildingBlock getHistoryForType getPropertyInfo printLog registerExecution rejectChanges sendEmail subscribeFor

Properties

datamodel

datamodel: DataModel

Datamodel currently saved on the server.

Note that when you access this inside a callback of Api.subscribeFor, the datamodel already contains the corresponding changes

http

http: Http

Allows performing Http(s)-calls to third-party REST APIs.

metamodel

metamodel: MetamodelApi

Api for the metamodel.

survey

survey: SurveyApi

Api for managing surveys

user

user: UserApi

Api for accessing user information

userGroup

userGroup: UserGroupApi

Api for accessing user group information

Methods

createDate

  • createDate(milliseconds: number): ApiDate

    Create a date that can be set as attribute value or can be used within date intervals.

    Parameters

    • milliseconds: number

      Number of milliseconds since Jan 01 1970 (UTC) Only use this to create date objects if you want to assign them to building blocks.

    Returns ApiDate

    Example

    var currentDate = api.createDate(new Date().getTime());
  • createDate(dateValue: string): ApiDate

    Create a date that can be set as attribute value or can be used within date intervals.

    Parameters

    Returns ApiDate

  • createDate(
        year: number,
        month: number,
        day: number,
        hour: number,
        minutes: number,
        seconds: number,
        milliseconds: number,
    ): ApiDate

    Create a date that can be set as attribute value or can be used within date intervals.

    Parameters

    • year: number

      Year of the date

    • month: number

      Month of the date (indexed from 0 to 11)

    • day: number

      Day of the month (starting at 1)

    • hour: number

      Hour of the day

    • minutes: number

      Minutes of the hour

    • seconds: number

      Seconds of the minute

    • milliseconds: number

      Milliseconds of the second

    Returns ApiDate

getHistoryForBuildingBlock

  • getHistoryForBuildingBlock(
        buildingBlockId: number,
        typePersistentName: BuildingBlockType,
    ): BBChange[]

    Get history for Building Block.

    Parameters

    • buildingBlockId: number

      Id of the building block

    • typePersistentName: BuildingBlockType

      Persistent name of the type of the building block type

    Returns BBChange[]

getHistoryForType

getPropertyInfo

  • getPropertyInfo(
        buildingBlockType: BuildingBlockType,
        property: string,
    ): PropertyInfo

    Gets inner properties of Building Block attribute by its persistent name (mandatory, multiple and type attribute properties are available)

    Parameters

    • buildingBlockType: BuildingBlockType

      Type of the building block

    • property: string

      Persistent name of the property

    Returns PropertyInfo

    Example

    var propertyInfoObject = api.getPropertyInfo("Project", "Accountability");
    // Create the string to be logged
    var propertyInfo = 'Project - Accountability '
      + '(type: ' + propertyInfoObject.type
      + ', multiple: ' + propertyInfoObject.multiple
      + ', mandatory: ' + propertyInfoObject.mandatory + ')';
    // log the information
    api.printLog(propertyInfo);

printLog

  • printLog(message: string): void

    Log a message to the script log

    Parameters

    • message: string

      Message to print

    Returns void

    Remarks

    This is the only way to log information. Do NOT try to use log.debug or similar things.

registerExecution

  • registerExecution(yourFunction: () => void): void

    Register a callback function which gets called when the script is specifically executed.

    Parameters

    • yourFunction: () => void

      Function to run when executing this script

    Returns void

    Remarks

    This and Api.subscribeFor are the only two functions that should be called at the top level scope of a plugin script.

    Example

    api.registerExecution(test);

    function test() {
      api.printLog('Function test executing');
    }

rejectChanges

  • rejectChanges(message?: string): never

    If this is called in a Api.subscribeFor callback, it will reject all changes to the datamodel that caused the callback. The script will exit immediately. A corresponding error message will be shown to the user who triggered the change. If this change was caused from the REST API, the error message will be returned as response.

    Parameters

    • Optionalmessage: string

      Optional message to be displayed to the user who triggered the change

    Returns never

    Remarks

    This is only intended for usage in callbacks for Api.subscribeFor! Do not use it in callbacks to Api.registerExecution, as this might have unintended side effects.

sendEmail

  • sendEmail(recipient: string, subject: string, content: string): -1 | 1

    Sends emails as a plain text. Returns an integer value of 1 if email was sent successfully, -1 if not.

    Please see the Subscriptions for more information on how to configure Mail-notifications. // TODO: Delete or specify

    Parameters

    • recipient: string

      Email address of recipient

    • subject: string

      Subject of the email

    • content: string

      Plain text content of the email

    Returns -1 | 1

    Example

    var subject = "Example subject";
    var content = "Example mail content"
    api.sendEmail(user.getEmail(), subject, content);

subscribeFor

  • subscribeFor(
        buildingBlockType: BuildingBlockType,
        yourFunction: SubscriptionCb,
    ): void

    Subscribes for changes at a Building Block Type. More than one function can subscribe for a certain Building Block Type. The system will call the function for each of these subscriptions.

    Parameters

    • buildingBlockType: BuildingBlockType

      Type of the building blocks for which to listen to changes

    • yourFunction: SubscriptionCb

      Callback called when a change occurs

    Returns void

    Remarks

    This and Api.registerExecution are the only two functions that should be called at the top level scope of a plugin script.

    Example

    api.subscribeFor('ItService', test);

    // This comment is necessary for autocompletion in the editor to work.
    // You dont need it for the script itself to work.
    /**
     @param {BuildingBlockType} bbt
     @param {ChangeEvent} ev
    */   (Note: Remove the \ here)
    function test(bbt, ev) {
      for (var i = 0; i < ev.length; i++) {
        var e = ev[i];
        if (e.changeType === 'DELETE') {
          var bb = api.datamodel.findByTypeAndId(bbt, e.id);
        }
      }
    }

Settings

Member Visibility

On This Page

Properties
Methods