web sdk macros

Working with macros

A macro in Security Center is an entity that contains C# code. Macros run server-side and can automate tasks, react to events, or integrate with external systems. The Web SDK lets you query, create, publish, start, stop, and monitor macros through REST endpoints.

Required privileges

Macro requests require access to the macro's partition.

Operation	Required access
List and read macro properties	View macro properties
Start, execute, and stop macros	Execute macros
Create macros, edit source code, set draft state, and publish macros	Administrator

Querying macros

Start by listing macro entities and reading their stored source, draft state, and active execution data.

List all macros

GET /report/EntityConfiguration?q=EntityTypes@Macro,Page=1,PageSize=100

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "Guid": "{macro-guid-1}"
      },
      {
        "Guid": "{macro-guid-2}"
      }
    ]
  }
}

Get macro properties

GET /entity?q=entity={macro-guid},Name,SourceCode,IsDraft,RunningState,DefaultParameters

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Name": "MyMacro",
      "SourceCode": "using Genetec.Sdk.Scripting;\npublic sealed class myMacro : UserMacro\n{\n    public override void Execute()\n    {\n        // macro logic here\n    }\n    protected override void CleanUp() { }\n}",
      "IsDraft": false,
      "RunningState": "Running",
      "DefaultParameters": []
    }
  }
}

Available fields

• Name - Macro name.
• SourceCode - The C# source code currently stored on the macro.
• IsDraft - When true, the macro cannot be executed.
• RunningState - A coarse macro status field. Use /activemacrosdetails when you need the active execution instances and execution IDs.
• DefaultParameters - Array of default parameter values for the macro's execution context.

Newly created macros start with template source code that still contains throw new NotImplementedException();, so replace or edit it before you expect useful execution behavior.

Creating macros

Create the macro entity first, and then replace the default source with your own code.

Create a macro

POST /entity?q=entity=NewEntity(Macro),Name=MyMacro,Guid

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Guid": "{new-macro-guid}"
    }
  }
}

The macro is created with default template source code. Use SetSourceCode to replace it.

Set source code

POST /entity?q=entity={macro-guid},SetSourceCode({url-encoded-source-code})

Response

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes

• Pass the URL-encoded source directly. Do not wrap it in %22...%22.
• The macro is compiled when the source code is set, unless the macro is in draft mode. Draft macros store the source without compiling; compilation occurs when the macro is published.
• If compilation fails, the call returns an error and the previously stored source remains in place.
• Only administrators can set macro source code.

Create a macro with source code

You can combine creation and source code in a single request:

POST /entity?q=entity=NewEntity(Macro),Name=MyMacro,SetSourceCode({url-encoded-source-code}),Guid

Use the same unquoted SetSourceCode({url-encoded-source-code}) form here.

Draft and publish

A macro in draft state cannot be executed. Use SetMacroToDraft and PublishMacro to toggle the draft state.

Set a macro to draft

POST /entity?q=entity={macro-guid},SetMacroToDraft()

Response

{
  "Rsp": {
    "Status": "Ok"
  }
}

This sets IsDraft to true. Only administrators can set macros to draft.

Publish a macro

POST /entity?q=entity={macro-guid},PublishMacro()

Response

{
  "Rsp": {
    "Status": "Ok"
  }
}

This sets IsDraft to false and recompiles the source code. If compilation fails, the call returns an error and the macro stays in draft state.

Starting macros

Both methods start the macro using its default parameters. The Web SDK does not support passing custom parameter values at execution time. Configure default parameters in Config Tool before starting the macro.

Using the action endpoint

POST /action?q=StartMacro({macro-guid})

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": []
  }
}

This starts the macro but does not return the execution ID. To get the execution ID, use /activemacrosdetails after starting the macro, or use the Execute() method instead.

Using the Execute method

POST /entity?q=entity={macro-guid},Execute()

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "Execute": "{execution-id}"
    }
  }
}

This starts the macro and returns the execution ID in the response. Use this execution ID to stop the specific instance.

Notes

• The same macro can have multiple instances running at the same time unless it is configured for single-instance execution.
• Each instance gets a unique execution ID.

Stopping macros

There are two ways to stop a running macro instance. Both require the execution ID. Use StopMacro(...) from /action when you only have the execution ID. Use AbortInstance(...) from /entity when you are calling the method on a specific macro entity, where entity={macro-guid} identifies the macro and AbortInstance({execution-id}) identifies the running instance.

Using the action endpoint

POST /action?q=StopMacro({execution-id})

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": []
  }
}

Using the AbortInstance method

POST /entity?q=entity={macro-guid},AbortInstance({execution-id})

Response

{
  "Rsp": {
    "Status": "Ok"
  }
}

Notes

• Get execution IDs from /activemacrosdetails or from the Execute() response.
• Both methods stop the same execution instance.

Monitoring running macros

Use the active-macro endpoints to see which macros are currently running and which execution IDs they were assigned. Use /activemacrosdetails to retrieve execution IDs for stopping or tracking specific macro instances.

List running macro GUIDs

GET /activemacros

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      "{macro-guid-1}"
    ]
  }
}

The result is an empty array when no macros are running. If the same macro has multiple instances running, its GUID appears once per instance.

List running macro details

GET /activemacrosdetails

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": [
      {
        "Entity": "{macro-guid}",
        "ExecutionId": "{execution-id}",
        "Instigator": "{user-guid}",
        "StartTime": "2026-03-14T06:05:48.5880352Z"
      }
    ]
  }
}

Response fields

• Entity - The GUID of the macro entity.
• ExecutionId - The unique identifier for this execution instance.
• Instigator - The GUID of the user who started the macro.
• StartTime - The UTC timestamp of when the macro started.

The result is an empty array when no macros are running.

Macro assembly references

Retrieve the list of assembly references configured for macro compilation in system configuration:

GET /entity?q=entity=00000000-0000-0000-0000-000000000007,GetMacroAssemblyReferences()

Response

{
  "Rsp": {
    "Status": "Ok",
    "Result": {
      "GetMacroAssemblyReferences": []
    }
  }
}

Notes

• The entity 00000000-0000-0000-0000-000000000007 is the system configuration entity.
• Returns an array of assembly reference strings configured for macro compilation.

See also

• The /action endpoint: The /action endpoint and operational commands.
• The /entity endpoint: The /entity endpoint and shared q= query syntax.
• Referencing entities: Entity discovery, search, and parameter formats.