Sc4SAPCmd - Command line tool

This page contains information about the command line tool that comes with "Shortcut for SAP systems", especially for using it with XML files. It is addressed to developers and admins and is available in English only.

The command line tool offers 2 options for calling it:

1.: Using a variant:

sc4sapcmd <function> <variant>

2.: Using an XML file:

sc4sapcmd <xml file>

The first option - using a variant - does not need much more information than already available in the program documentation.

The second option is a little bit more complex, as all necessary data for executing the command line tool has to be given in an XML file, following the defined "XML schema".

The XML schema is supplied in the subfolder "xml" in file "Sc4SAPCmd.xsd". The XML schema describes the structure of the XML files. There are several tools available, that makes it easy to developers or admins to show it in a readable form resp. to use it for programming purposes or check the correctness of created XML files.

You will also find some examples in the "xml" subfolder, that comes with our application, e.g. for:

saving system specific configuration data
unlocking users (use it for example in combination with a Chatbot or in a website for self services)
deletion of table data (e.g. for deleting developer keys in productive environments)
copying data from Production to Quality system (e.g. for getting data of the Quality system closer to the data from Productive system and therefore making the Quality system better usable for bug fixing, debugging, testing etc.)
and others.

On this page the general structure of the XML files is explained.

Details, examples and use cases of the individual task types can be found here.

The structure of the XML files

The root element of the XML file is an element named "ExecutionChain". It must contain at least one element named "Task" and may contain some data valid for all tasks in it, for example a connection to be used as default.

ID	optional	An ID for the execution chain, can be used programmatically to identify between execution chains.
Comment	optional	A comment / short description of the execution chain.
DefaultConnection	optional	A default connection, that will be used when no connection was specified in the task.
ForcedConnection	optional	A connection that will be used prior to a connection specified in the task.
AllowRepeatedProcessing	optional	Decide whether multiple processing of the file is allowed ("true") or not ("false"). Default: true.
IgnoreUnknownElements	optional	If set to true, not known elements and attributes in the XML file will be ignored. If set to "false", not known elements or attributes will result in a return code 4. Default is "false". When enriching the XML file with own data, the value should be set to "true".
Task	obligatory, 1 or more	A concrete task resp. function that is to be executed.
Result	(output)	Result information after execution of the execution chain. - Processed: date and time of the execution - ReturnCode: highest return code of the executed tasks - Message: 0..* messages containing information

Find here a simple example of an execution chain. It contains only a single task for unlocking a user:

<Comment>Unlocking SAP user, generated by ChatBot system in chat #309823590</Comment>

<Task>

<Connection>PX1/100, User Self service</Connection>

<Users>mbrink</Users>

</UnlockUser>

</Task>

</ExecutionChain>

After its execution the XML file will be enriched by information about the result of the processing, on task level as well as on chain level. The triggering process can use this information for further processing, e.g. for confirming the execution to the user:

<Comment>Unlocking SAP user, generated by ChatBot system in chat #309823590</Comment>

<Task>

<Connection>PX1/100, User Self service</Connection>

<Users>mbrink</Users>

<Result>

<Processed>2023-05-09T11:35:42.528</Processed>

<ReturnCode>0</ReturnCode>

<Message>User MBRINK unlocked and validity range removed.</Message>

<Message>Done for 1 user(s). 1 user(s) unlocked. For 1 user(s) the validity range was removed.</Message>

</Result>

</UnlockUser>

</Task>

<Result>

<Processed>2023-05-09T11:35:42.528</Processed>

<ReturnCode>0</ReturnCode>

</Result>

</ExecutionChain>

Another example: a task for assigning a new password.

<Comment>Assign new password to SAP user, generated by ChatBot system in chat #309816689</Comment>

<Task>

<Connection>PX1/100, User Self service</Connection>

<User>mbrink</User>

</SetIndividualPassword>

</SetPassword>

</Task>

</ExecutionChain>

After its execution, containing the information about the result of the processing:

<Comment>Assign new password to SAP user, generated by ChatBot system in chat #309816689</Comment>

<Task>

<Connection>PX1/100, User Self service</Connection>

<User>mbrink</User>

</SetIndividualPassword>

<Result>

<Processed>2023-05-09T11:59:26.050</Processed>

<ReturnCode>0</ReturnCode>

<Message>Generated password for user MBRINK: Tv<72z2/FfZordP+q$Hg&B99NW[D(PkXPFAQPqff</Message>

<Message>Done for 1 user(s). Password set for 1 user(s).</Message>

</Result>

</SetPassword>

</Task>

<Result>

<Processed>2023-05-09T11:59:26.050</Processed>

<ReturnCode>0</ReturnCode>

</Result>

</ExecutionChain>

When processing the "Result" information, consider that XML has some character replacements:

Character	XML notation
<	<
>	>
&	&
"	"
'	'

Therefore, before forwarding the password to the user, the XML notation of special characters has to be reverted:

Generated password for user MBRINK: Tv<72z2/FfZordP+q$Hg&B99NW[D(PkXPFAQPqff

-> Generated password for user MBRINK: Tv<72z2/FfZordP+q$Hg&B99NW[D(PkXPFAQPqff

The tasks cover the several functions of "Shortcut for SAP systems". In a "Task" element a concrete task resp. function is to be given as a choice of ExecProgram, UnlockUser, AssignRoleOrProfile, R3trans etc.:

Each Task has an attribute "StopOnError", which can be used to stop the whole execution chain if the task fails. So, a value "true" would stop the chain after the tasks indicates an error after its execution. With value "false" an error will be ignored and the execution of the chain will be continued.

Also a task may have an ID (optional) and a Comment (optional). Also a Variant may be specified optionally. Some tasks allow a mix of a Variant and given data in the XML file in that way, that data in the XML file will overwrite the values of the Variant.

As most tasks use a single connection, there is also a type covering this issue:

XML: base for a task with a single connection

A task with a single connection contains 2 optional elements:

Connection: here a connection can be specified that will be used as default for the task.

ForcedConnection: here a connection can be specified that will be used prior to all other given connections. Also a "ForcedConnection" on chain level will be overwritten.

As there are several possibilities to specify the connection to be used, find here a prioritization.

"ForcedConnection" on task level
"ForcedConnection" on chain level
"Connection" of the task
the connection in a given Variant
"DefaultConnection" on chain level

This cascading approach makes it possible to set the connection quite flexible. For example, if there are Variants available containing all the data, you can easily use these Variants also for other connections by specifying a "ForcedConnection" on chain level. For single exceptions you can specify a "ForcedConnection" on task level.

So finally a concrete task has

the elements of the task base (attribute "StopOnError", elements "ID", "Comment", "Variant" - all optional)
if it is a task with a single connection, it has also optional elements "Connection" and "ForcedConnection"
and the data specific for the task.

Example: Task type "UnlockUser"

More details on the individual task types