Sc4SAPCmd - Command line tool

Direkt zum Seiteninhalt
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 in the program directory

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.
Execution chain
IDoptionalAn ID for the execution chain, can be used programmatically to identify between execution chains.
CommentoptionalA comment / short description of the execution chain.
DefaultConnectionoptionalA default connection, that will be used when no connection was specified in the task.
ForcedConnectionoptionalA 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.
Resumptionoptional
Resumption of an aborted execution chain. Default: 'false'. If 'true', an aborted execution chain can be resumed at the task that caused the termination. The information in the 'ResumeAtTask' tag is used to skip the tasks that have already been processed. After execution of the last task the 'ResumeAtTask' tag will be removed.
ResumeAtTaskoptional
Only effective if 'Resumption' is set to true. Typically this tag will be maintained automatically, but it is also possible to set the value manually to enforce the execution chain to skip tasks and start the processing with the number of the task specified in this tag.
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:
<ExecutionChain>  
 <ID>309823590</ID>  
 <Comment>Unlocking SAP user, generated by ChatBot system in chat #309823590</Comment>  
 <Task>
   <UnlockUser StopOnError="false">
     <Connection>PX1/100, User Self service</Connection>  
     <Users>mbrink</Users>  
     <RemoveValidityRange>true</RemoveValidityRange>  
   </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:
<ExecutionChain>
  <ID>309823590</ID>  
  <Comment>Unlocking SAP user, generated by ChatBot system in chat #309823590</Comment>  
  <Task>
    <UnlockUser StopOnError="false">
      <Connection>PX1/100, User Self service</Connection>
      <Users>mbrink</Users>
      <RemoveValidityRange>true</RemoveValidityRange>
     <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.
<ExecutionChain>  
 <ID>309816689</ID>  
 <Comment>Assign new password to SAP user, generated by ChatBot system in chat #309816689</Comment>
 <Task>
   <SetPassword StopOnError="false">
     <Connection>PX1/100, User Self service</Connection>
     <SetIndividualPassword>
       <GeneratePw>true</GeneratePw>
       <User>mbrink</User>
     </SetIndividualPassword>
   </SetPassword>
 </Task>  
</ExecutionChain>
After its execution, containing the information about the result of the processing:
<ExecutionChain>  
   <ID>309816689</ID>  
   <Comment>Assign new password to SAP user, generated by ChatBot system in chat #309816689</Comment>  
   <Task>
      <SetPassword StopOnError="false">
         <Connection>PX1/100, User Self service</Connection>
         <SetIndividualPassword>
            <GeneratePw>true</GeneratePw>
            <User>mbrink</User>
         </SetIndividualPassword>
        <Result>
           <Processed>2023-05-09T11:59:26.050</Processed>
           <ReturnCode>0</ReturnCode>
           <Message>Generated password for user MBRINK: Tv&lt;72z2/FfZordP+q$Hg&amp;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
<
&lt;
>
&gt;
&
&amp;
"
&quot;
'
&apos;
Therefore, before forwarding the password to the user, the XML notation of special characters has to be reverted:
       Generated password for user MBRINK: Tv&lt;72z2/FfZordP+q$Hg&amp;B99NW[D(PkXPFAQPqff
  -> Generated password for user MBRINK: Tv<72z2/FfZordP+q$Hg&amp;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.:
XML file: the Task types
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.
XML: base elements of a task
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.
  1. "ForcedConnection" on task level
  2. "ForcedConnection" on chain level
  3. "Connection" of the task
  4. the connection in a given Variant
  5. "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"

UnlockUser task
Shortcut IT GmbH
Försterstr. 11A
31275 Lehrte

Zurück zum Seiteninhalt