Skip to end of metadata
Go to start of metadata

Table Of Contents

Overview

This document describes the APIs that are available for use by consultants and developers to customize the VDI workflows available in Visual Enterprise Generator 8.0 or later.

It covers the following areas:

  • The new SAP Python APIs added for use by Python scripts executed by Visual Enterprise Generator.
  • The VDI web service used to start and managed VDI workflow jobs.

It does not cover:

Applicable To
Visual Enterprise Generator 8.0 or later

 

Web Service API

The VDI web service API is a new web service in Visual Enterprise Generator 8.0 for triggering and managing VDI workflow jobs. It is used by the Upload Client to start and manage conversion jobs, and can also be used by third parties for a more advanced integration with Visual Enterprise Generator.

Getting Started

Please refer to note 1694219 , attachment UploadClient_WebService_Template_VEG_90.ZIPfor the WSDL for this web service. The WSDL file is named UploadClient_ERPIntegration_WSDL.WSDL, use this file to generate your proxies for communicating with this service.

Consumers of this web service must support streaming MTOM in order to upload files to be used by jobs, this is supported by .NET and modern Java web service stacks.

Workflow List

To get the list of possible VDI workflows that jobs can be started for, the method WorkflowGetAvailable() can be called without having performed any authentication.

WorkflowGetAvailableResponse

This is the response object returned by WorkflowGetAvailable().

Field NameTypeMandatoryDescription
WorkflowSystemConnectionsArray of WorkflowSystemConnectionYesThe list of VDI workflows that can be used for conversion jobs
WorkflowSystemConnection
Field NameTypeMandatoryDescription
WorkflowNameStringYesThe name of the VDI workflow.
ClientNameStringNoThe client of the SAP system associated with the workflow (e.g. 002)
SystemNameStringNo

The name of the SAP system associated with the workflow.

Corresponds to the name in SAP GUI on the server and user account where Visual Enterprise Generator has been configured. This name should match up with the name used in SAP GUI on the system where the Upload Client is used, for document linking in Upload Client to work.


Authentication

In order to use any of the authenticated web service calls, a call to the UserAuthenticate() web service method must be performed to obtain a session ID which should be supplied with all subsequent requests, and acts as an authentication token.

If authentication fails, a SOAP fault will be raised by this call with more information.

UserAuthenticateRequest

This is the request object which must be passed into UserAuthenticate().

Field NameTypeMandatoryDescription
UserNameStringYesThe SAP user name to authenticate. This should be the name of a user in the SAP system associated with the workflow.
PasswordStringYesThe password of the user being authenticated
WorkflowNameStringYesThe name of the workflow against which to authenticate the user. The workflow will have an associated SAP system.
CultureNameStringYesThe culture name to use for the user. This affects functions which support localized values, like the localized job report retrieval. This value is in the Windows culture name format, see the Culture Name column in http://msdn.microsoft.com/en-us/goglobal/bb896001.aspx for a list of possible values.
ShouldCreateSessionBooleanNoWhether or not an isual Enterprise Generator user session should be created. This should be set to true if subsequent calls will be made which use the created session, and  set to false if the authentication request will not be followed by subsequent calls, and it is just an authentication check.
UserAuthenticateResponse

This is the response object returned by UserAuthenticate() in the event of successful authentication.

Field NameTypeMandatoryDescription
SessionIdStringYesThe session ID that can be used as an authentication token in subsequent web service calls, by passing it through in the SessionId field of other request objects.


Deauthentication

In order to preemptively clear user sessions, the method UserDeauthenticate() can be called to delete a session and all information associated with it.

UserDeauthenticateRequest

This is the request object which must be passed in to UserDeauthenticate().

Field NameTypeMandatoryDescription
SessionIdStringYesThe session ID obtained from a previous UserAuthenticate() call.


UserDeauthenticateResponse

This object contains no fields.


File Uploading

All conversion jobs started using this web service require an input file in order to start. This file should be uploaded to the server first before starting the job.

The sequence of events is as follows:

  1. The FileUploadBegin() method is called to obtain a unique ID for the file to be uploaded.
  2. The FileUploadChunk() method is called as many times as needed to transfer all the file data to the server.
  3. The FileUploadEnd() method is called to mark an uploaded file as complete. After making this call the file unique ID can be passed to methods that expect it.

FileUploadBegin()

This method generates a new unique ID to use for subsequent file upload calls.

FileUploadBeginRequest

This is the request object that must be passed into the FileUploadBegin() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
FileUploadBeginResponse

This is the response object returned by the FileUploadBegin() call.

Field NameTypeMandatoryDescription
UniqueIdStringYesThe unique ID for the file


FileUploadChunk()

This method uploads a chunk of a file to the server. If an error occurs, a SOAP fault will be raised by this call, containing additional information.

FileUploadChunkRequest

This is the request object that must be passed into the FileUploadChunk() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID for the file a chunk is being uploaded for
OffsetIntegerYesThe starting offset in the file where the data for this chunk should be written
LengthIntegerYesThe size in bytes of this chunk
StreamByte ArrayYesThe data for this chunk. Depending on the platform, this will be represented as a Stream on .NET, or a byte array on Java (depending on the web service stack). Transported using MTOM encoding.
FileUploadChunkResponse

This object contains no fields.


FileUploadEnd()

This methods marks a file which was being uploaded as completed. The file cannot be written to after this call.

FileUploadEndRequest

This is the request object that must be passed into the FileUploadEnd() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID of the file to mark as completed, obtained from a previous FileUploadBegin() call

FileUploadCancel()

This methods removes all information for a file which was being uploaded. The file cannot be written to after this call, and the unique ID no longer exists on the server.

FileUploadCancelRequest

This is the request object that must be passed into the FileUploadCancel() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
UniqueIdStringYesThe unique ID of the file to remove, obtained from a previous FileUploadBegin() call


Starting Jobs

Once the input file to a job has been uploaded, the job can be started by invoking JobStartWithUploadedFile(). If the job could not be started successfully, a SOAP fault is raised.

JobStartWithUploadedFileRequest

This is the request object that must be passed into the JobStartWithUploadedFile() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
InputFileUniqueIdStringYesThe unique ID of the uploaded file which should be used as the input to the VDI processing job
WorkflowNameStringYesThe name of the VDI workflow for which to start a job
JobNameStringNoThe name to give the processing job
JobStartWithUploadedFileResponse

This is the response object returned by the JobStartWithUploadedFile() call.

Field NameTypeMandatoryDescription
JobIdIntegerYesThe Visual Enterprise Generator job ID for the started job


Canceling Jobs

 To cancel a currently running job, the JobCancel() method can be invoked. If the job could not be canceled successfully, a SOAP fault is raised.

JobCancelRequest
Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
VegJobIDIntegerYesThe Visual Enterprise Generator job ID of the job to cancel

 

JobCancelResponse

 This object contains no fields.


Job Monitoring

To query the status of running jobs, in order to determine whether or not they have completed, the JobGetStatus() call can be used.

JobGetStatusRequest

This is the request object that must be passed into the JobGetStatus() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
JobIDsArray of IntegerYesAn array of the Visual Enterprise Generator job IDs to query
JobGetStatusResponse

This is the response object returned by the JobGetStatus() call.

Field NameTypeMandatoryDescription
JobsArray of JobStatusInfoYesAn array of JobStatusInfo objects, corresponding to each job ID supplied in the request JobIDs field.
JobStatusInfo

This is the type of an element in the Jobs field of the JobGetStatusResponse object.

Field NameTypeMandatoryDescription
IdIntegerYesThe Visual Enterprise Generator job ID with which this status object is associated
StatusEnumYes

The current status of this job. Possible values are the following:

  • Unknown: Job does not exist or status could not be determined
  • Queued: Job has been queued with Visual Enterprise Generator
  • Running: Job is currently running
  • Completed: Job has finished, consult the Outcome field to determine whether or not it was successful
OutcomeEnumNo

This field is only set to a meaningful value if the job Status is Complete. Possible values are the following:

  • Unknown: Job does not exist or is not yet complete
  • Success: Job completed with no errors or warnings
  • Warning: Job completed, but there were some warnings
  • Error: Job completed, but there were some errors
  • Aborted: Job was canceled by user
  • Paused: Job is currently paused


Job Results

After a job completed successfully, it can be useful to programmatically retrieve information about what actions the job performed. As an example, it is possible to programmatically determine the SAP DIR IDs for completed jobs, as well as whether or not those jobs have viewables attached to the DIRs.

This is achieved by calling the JobGetResult() method.

JobGetResultRequest

This is the request object that must be passed into the JobGetResult() call.

Field NameTypeMandatoryDescription
SessionIdStringYesThe authenticated session ID obtained from a prior UserAuthenticate() call.
JobIDsArray of IntegerYesAn array of the Visual Enterprise Generator job IDs to query
JobGetResultResponse

This is the response object returned by the JobGetResult() call.

Field NameTypeMandatoryDescription
JobsArray of JobResultInfoYesAn array of JobResultInfo objects, corresponding to each job ID supplied in the request JobIDs field.
JobResultInfo

This is the type of an element in the Jobs field of the JobGetResultResponse object.

Field NameTypeMandatoryDescription
IdIntegerYesThe Visual Enterprise Generator job ID with which this result object is associated
ResultsArray of JobResultYes

An array of JobResult objects containing the results for the job

JobResult

This is the type of an element in the Results field of the JobResultInfo object.

Field NameTypeMandatoryDescription
CategoryStringNoThe category of this result (a grouping field). VDI workflows will use a category of SAP for system created results.
PathStringNo

The path of the result (a sub-grouping field). The value used here is workflow-specific.

NameStringYesThe name associated with the result
ValueStringYesThe value associated with the result


Job Reporting

The job report is a human-readable report of what occurred in a job, it is not intended for machine consumption, since different languages will result in completely different data in the returned XML.

A job report is retrieved by invoking the JobGetLocalisedReportAsXml() method.

JobGetLocalizedReportRequest

This is the request object passed to JobGetLocalisedReportAsXml().

Field NameTypeMandatoryDescription
JobIdIntegerYesThe Visual Enterprise Generator job ID for which to get the job report
LanguageStringNo

The ISO 3166 two letter language code specifying the language in which the job report should be returned.

Not all languages have localisations for the job report. The major supported languages are English, German, Chinese, Japanese, Russian, Spanish, and Portuguese.

JobGetLocalizedReportResponse

This is the response object returned by JobGetLocalisedReportAsXml().

Field NameTypeMandatoryDescription
JobReportStringYesThe localised job report, in XML format.


  • No labels