APADM Command Line Utility

This topic provides examples using commands for the APADM command line utility. The APADM application is a command line utility that can be used to perform some administrative tasks from the command line.

Prerequisites

  • AgilePoint NX OnPremises or AgilePoint NX Private Cloud.
  • To use the ExecutionTimeout argument, you must have a release that includes Intermediate Fix 08.0081.02 or higher, or AgilePont NX v6.x or higher.
  • To use the SyncSocialAccounts argument, you must have AgilePoint v5.0 R2 with Intermediate Fix 08.0082.01 or higher, or AgilePont NX v6.x or higher.

Good to Know

How to Start

  1. In a command prompt, change directories to (AgilePoint Server instance installation folder) C:\Program Files\AgilePoint\AgilePointServerInstance\Tools

Procedure

  1. Run the following commands as necessary, using the following format:

    apadm.exe [command] [arguments] [domain\username] [password]

    The [domain\username] and [password] arguments are required for multi-tenant environments. These arguments are optional for single tenant environments.

    CommandDefinition

    -help
    Function:
    Shows all AgilePoint APADM commands.

    -ActivateDelegation
    Function:
    Activates a delegation instance using a unique delegation ID.
    Required Arguments:
    • [delegation ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ActivateDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer
    • apadm -ActivateDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer mydomain\admin password

    -AddDelegation
    Function:
    Creates a rule for delegating one user's tasks to another user.
    Required Arguments:
    • description
    • [from user]
    • [to user]
    • [start date]
    • [end date]
    • [recurrence weekdays string]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -AddDelegation MyDelegation mydomain\\liy.allen mydomain\\bob.hope 24-04-2018 3-8-2018 Monday http://mydomain:13487/AgilePointServer
    • apadm -AddDelegation MyDelegation mydomain\\liy.allen mydomain\\bob.hope 24-04-2018 3-8-2018 Monday http://mydomain:13487/AgilePointServer mydomain\admin password

    -AddGroup
    Function:
    Creates a group in AgilePoint NX, and sets the ResponsibleUser parameter as the group lead.
    Required Arguments:
    • [group name]
    • description
    • [responsible user]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -AddGroup Development GroupDescription mydomain\\HR http://mydomain:13487/AgilePointServer
    • apadm -AddGroup Development GroupDescription mydomain\\HR http://mydomain:13487/AgilePointServer mydomain\admin password

    -AddRole
    Function:
    Creates a role in AgilePoint NX, and specifies the access right for the users assigned to the role.
    Required Arguments:
    • [role name]
    • description
    • [enabled]
    • [access rights]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -AddRole RegionalManagers RegionalWideManagers true 2 4 8 http://mydomain:13487/AgilePointServer
    • apadm -AddRole RegionalManagers RegionalWideManagers true 2 4 8 http://mydomain:13487/AgilePointServer mydomain\admin password

    -adduser
    Function:
    Adds a new user in the AgilePoint system.
    Required Arguments:
    • [LDAP path]
    • [AgilePoint Server URL]
    Optional Arguments:
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    • SyncSocialAccounts - Synchronizes users' email IDs with their Yammer and Lync IDs.
    Example:
    • apadm -adduser LDAP://dc=tusca,dc=com http://mydomain/AgilePointServer
    • apadm -adduser LDAP://dc=tusca,dc=com http://mydomain/AgilePointServer ExecutionTimeout=100
    • apadm -adduser LDAP://dc=tusca,dc=com http://mydomain/AgilePointServer ExecutionTimeout=100 mydomain\admin password

    -archive
    Function:
    Archives a process instance based on the specified process instance identifier by moving the set of process instance records from the workflow database to the archive database.
    Required Arguments:
    • [days] or [process instance ID] or [ProcessDefinitionName:ProcessInstaneName]
    • [AgilePoint Server URL]
    Optional Arguments:
    • -Y - Suppresses the interactive confirmation to proceed with the action.
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:

    The following example archives all processes that were completed or canceled 10 days ago.

    • apadm -archive 10 http://mydomain/AgilePointServer
    • apadm -archive 10 http://mydomain/AgilePointServer mydomain\admin password

    The following example archives the process with the specified process instance ID.

    • apadm -archive 501630F1C09743dbBA25FAC9C3DA7524 http://mydomain/AgilePointServer
    • apadm -archive 10 http://mydomain/AgilePointServer -Y ExecutionTimeout=100
    • apadm -archive 501630F1C09743dbBA25FAC9C3DA7524 http://mydomain/AgilePointServer mydomain\admin password

    -cancelDelegation
    Function:
    Deactivates a delegation instance using a delegation ID.
    Required Arguments:
    • [delegation ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -cancelDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer
    • apadm -cancelDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer mydomain\admin password

    -CancelPID
    Function:
    Cancels the process instance based on a specified Create Process Instance.
    Required Arguments:
    • [process instance ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -CancelPID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer
    • apadm -CancelPID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer mydomain\admin password

    -DeletePID
    Function:
    Permanently deletes a process instance.
    Required Arguments:
    • [process instance ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -DeletePID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer
    • apadm -DeletePID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer mydomain\admin password

    -ExpRole
    Function:
    Exports a role to an XML file from the AgilePoint system.

    For more information, refer to Export Roles.

    Required Arguments:
    • [role name1]
    • [role name2]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ExpRole MangerRole UserRole http://mydomain:13487/AgilePointServer
    • apadm -ExpRole MangerRole UserRole http://mydomain:13487/AgilePointServer mydomain\admin password

    -ExpGroups
    Function:
    Exports the AgilePoint groups to an XML file from the AgilePoint system.

    For more information, refer to Export Groups.

    Required Arguments:
    • [group name1]
    • [group name2]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ExpGroups HRGroup ManagerGroup http://mydomain:13487/AgilePointServer
    • apadm -ExpGroups HRGroup ManagerGroup http://mydomain:13487/AgilePointServer mydomain\admin password

    -ImpGroups
    Function:
    Imports the AgilePoint groups from an XML file to the AgilePoint system.

    For more information, refer to Import Groups.

    Required Arguments:
    • [The path of your group file in XML format]
    • [action] - OverrideExisting, MergeExisting, DoNotOverrideExisting
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ImpGroups c:\Users\Admin\Desktop\GroupEntries.xml OverrideExisting http://mydomain:13487/AgilePointServer
    • apadm -ImpGroups c:\Users\Admin\Desktop\GroupEntries.xml OverrideExisting http://mydomain:13487/AgilePointServer admin password

    -ImportRole
    Function:
    Imports the AgilePoint role to the AgilePoint system.

    For more information, refer to Import Roles.

    Required Arguments:
    • [role name]
    • [action] - OverrideExisting, MergeExisting, DoNotOverrideExisting
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ImportRole c:\Users\Admin\Desktop\Roles.xml OverrideExisting http://mydomain:13487/AgilePointServer
    • apadm -ImportRole c:\Users\Admin\Desktop\Roles.xml OverrideExisting http://mydomain:13487/AgilePointServer mydomain\admin password

    -RemoveGroup
    Function:
    Permanently removes an AgilePoint group with the specified group name.
    Required Arguments:
    • [group name]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -RemoveGroup ProjectLead http://mydomain:13487/AgilePointServer
    • apadm -RemoveGroup ProjectLead http://mydomain:13487/AgilePointServer mydomain\admin password

    -RemoveRole
    Function:
    Permanently removes a role from the AgilePoint system.
    Required Arguments:
    • [role name]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -RemoveRole Development http://mydomain:13487/AgilePointServer
    • apadm -RemoveRole Development http://mydomain:13487/AgilePointServer mydomain\admin password

    -restore
    Function:
    Restores a process.
    Required Arguments:
    • [process instance ID] or [ProcessDefinitionName:ProcessInstaneName]
    • [AgilePoint Server URL]
    Optional Arguments:
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:
    • apadm -restore 501630F1C09743dbBA25FAC9C3DA7524 http://mydomain/AgilePointServer
    • apadm -restore ExpenseReport:JohnSmith-01-20-2010-09 http://mydomain/AgilePointServer ExecutionTimeout=100
    • apadm -restore ExpenseReport:JohnSmith-01-20-2010-09 http://mydomain/AgilePointServer ExecutionTimeout=100 mydomain\admin password

    -ResumePID
    Function:
    Resumes a suspended process instance. The process instance status is changed to running, and the statuses of all the work items (tasks) become Active.
    Required Arguments:
    • [process instance ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -ResumePID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer
    • apadm -ResumePID 827128D244B4F4D911776146DEAFFE03 http://mydomain:13487/AgilePointServer mydomain\admin password

    -rmDelegation
    Function:
    Permanently removes a delegation instance using a unique delegation ID.
    Required Arguments:
    • [delegation ID]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -rmDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer
    • apadm -rmDelegation 827228D244B4F4D9117776A4863B28EA http://mydomain:13487/AgilePointServer mydomain\admin password

    -syncgm
    Function:
    Synchronizes group members with Active Directory.
    Required Arguments:
    • [LDAP path]
    • [authentication domain name]
    • [AgilePoint Server URL]
    Optional Arguments:
    • [retry count] - An integer that specifies a number of times to retry the operation before quitting.
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    • SyncSocialAccounts - Synchronizes users' email IDs with their Yammer and Lync IDs.
    Example:
    • apadm -syncgm LDAP://dc=tusca,dc=com TUS http://mydomain/AgilePointServer
    • apadm -syncgm LDAP://dc=tusca,dc=com TUS http://mydomain/AgilePointServer mydomain\admin password

    In the following example, if synchronization fails, it retries 5 times as specified in the optional last parameter.

    • apadm -syncgm LDAP://dc=tusca,dc=com TUS http://mydomain/AgilePointServer 5 ExecutionTimeout=100
    • apadm -syncgm LDAP://dc=tusca,dc=com TUS http://mydomain/AgilePointServer 5 ExecutionTimeout=100 mydomain\admin password

    -rmprocdef
    Function:
    Permanently deletes the process model (process definition) and all of the process instances associated with the process model.
    Required Arguments:
    • [process definition name]
    • [AgilePoint Server URL]
    Optional Arguments:
    • -Y - Suppresses the interactive confirmation to proceed with the action.
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:
    • apadm -rmproc PurchaseRequest http://mydomain/AgilePointServer
    • apadm -rmproc PurchaseRequest http://mydomain/AgilePointServer -Y ExecutionTimeout=100
    • apadm -rmproc PurchaseRequest http://mydomain/AgilePointServer -Y ExecutionTimeout=100 mydomain\admin password

    -mgproc
    Function:
    Migrates process instances from one version to another version (called process migration).
    Required Arguments:
    • [process migration instruction XML file]
    • [AgilePoint Server URL]
    Optional Arguments:
    • -NoSchemaMigrate - Stops upgrading the schema to the latest updated schema.
    • -Run - Keeps the process running, even if an error occurs while running the operation. By default, if an error occurs, the process moves to a suspended state.
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:
    • apadm -mgproc C:\MyFolder\PurchaseRequest-2019-10-25T12_22_34_817_migration_instruction.xml http://mydomain/AgilePointServer
    • apadm -mgproc C:\MyFolder\PurchaseRequest-2019-10-25T12_22_34_817_migration_instruction.xml http://mydomain/AgilePointServer -NoSchemaMigrate -Run ExecutionTimeout=100
    • apadm -mgproc C:\MyFolder\PurchaseRequest-2019-10-25T12_22_34_817_migration_instruction.xml http://mydomain/AgilePointServer -NoSchemaMigrate -Run ExecutionTimeout=100 mydomain\admin password

    -sysinfo
    Function:
    Shows the AgilePoint system information.
    Required Arguments:
    • [AgilePoint Server URL]
    Optional Arguments:
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:
    • apadm -systeaminfo http://mydomain/AgilePointServer
    • apadm -systeaminfo http://mydomain/AgilePointServer ExecutionTimeout=100
    • apadm -systeaminfo http://mydomain/AgilePointServer ExecutionTimeout=100 mydomain\admin password

    -publishprocdef
    Function:
    Publishes the process model (process definition) in the specified release date from AgilePoint Server.
    Required Arguments:
    • [AgilePoint Server URL]
    • [folder] or [file]
    • [release date]
    Optional Arguments:
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:

    In this example, abc is a folder that contains XML files of process definition that need to be published and scheduled to be released on 1/20/2011.

    • apadm -publishprocdef http://mydomain/AgilePointServer abc 1/20/2011
    • apadm -publishprocdef http://mydomain/AgilePointServer abc 1/20/2011 ExecutionTimeout=100
    • apadm -publishprocdef http://mydomain/AgilePointServer abc 1/20/2011 ExecutionTimeout=100 mydomain\admin password

    In this example, expensereport.xml is an XML file of process definition that needs to be published.

    • apadm -publishprocdef http://mydomain/AgilePointServer expensereport.xml
    • apadm -publishprocdef http://mydomain/AgilePointServer expensereport.xml mydomain\admin password

    -UpdateDelegation
    Function:
    Updates a delegation object that has already been created.
    Required Arguments:
    • description
    • [from user]
    • [to user]
    • [start date]
    • [end date]
    • [recurrence weekdays string]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -UpdateDelegation Mydelegation mydomain\\liy.allen mydomain\\bob.hope 24-04-2018 3-8-2018 Monday http://mydomain:13487/AgilePointServer
    • apadm -UpdateDelegation Mydelegation mydomain\\liy.allen mydomain\\bob.hope 24-04-2018 3-8-2018 Monday http://mydomain:13487/AgilePointServer mydomain\admin password

    -UpdateGroup
    Function:
    Updates a group with a new description or group lead.
    Required Arguments:
    • [group name]
    • description
    • [responsible user]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -UpdateGroup Development GroupDescription mydomain\\HR http://mydomain:13487/AgilePointServer
    • apadm -UpdateGroup Development GroupDescription mydomain\\HR http://mydomain:13487/AgilePointServer mydomain\admin password

    -UpdateRole
    Function:
    Updates the description or access right selections of a role.
    Required Arguments:
    • [role name]
    • description
    • [access rights]
    • [enabled]
    • [AgilePoint Server URL]
    Optional Arguments:
    None
    Example:
    • apadm -UpdateRole RegionalManagers RegionalWideManagers 4 6 32 true http://mydomain:13487/AgilePointServer
    • apadm -UpdateRole RegionalManagers RegionalWideManagers 4 6 32 true http://mydomain:13487/AgilePointServer mydomain\admin password

    -analyzeclusterlog
    Function:
    Retrieves the log file information related to the cluster.
    Required Arguments:
    • [cluster log file]
    Optional Arguments:
    • ExecutionTimeout = [seconds] - Specifies a timeout value, in seconds, for the operation.
    Example:
    • apadm -analyzeclusterlog 20110521T043713Cluster.log
    • apadm -analyzeclusterlog 20110521T043713Cluster.log ExecutionTimeout=100
    • apadm -analyzeclusterlog 20110521T043713Cluster.log ExecutionTimeout=100 mydomain\admin password