CAA Web Services Home

 

Consuming the ENOVWSCntMgmtCpp CAA Web Service

Using the ENOVWSCntMgmtCpp CAA Web Service for document management
Use Case

Abstract

This article discusses the CAAENOVWSDotNet1_1Client use case. It describes how to use the C# client binding that can be generated using the wsdl.exe utility in order to consume the ENOVWSCntMgmtCpp CAA Web service. It provides a sample usage scenario that demonstrates how to handle lifecycle management.

What You Will Learn With This Use Case

This use case demonstrates how to write a client application that consumes the ENOVWSCntMgmtCpp CAA Web service. It helps you to:

[Top]

The CAAENOVWSDotNet1_1Client Use Case

CAAENOVWSDotNet1_1Client is a use case of the CAAENOVWS.edu framework that illustrates the ENOVWSCntMgmtCpp CAA Web service capabilities.

[Top]

What Does CAAENOVWSDotNet1_1Client Do

The sample usage scenario delivered with this use case contains the following steps:

The ENOVWSProdStructCpp CAA Web service is used in support of the primary objective of this use case, which is to manage documents using the ENOVWSCntMgmtCpp CAA Web service.

[Top]

Where To Find the CAAENOVWSDotNet1_1Client Code

The CAAENOVWSDotNet1_1Client use case is made of several classes located in both CAAENOVWSDotNet1_1Client.m and CAAENOVWSDotNet1_1ClientBase.m modules of the CAAENOVWS.edu framework:

<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1Client.m\src
<Install>\CAAENOVWS.edu\CAAENOVWSDotNet1_1ClientBase.m\src

The CAAENOVWSDotNet1_1ClientBase.m module (library) contains the following resources:

<Source>\CAAENOVWSCntMgmtCppProxy.cs
<Source>\CAAENOVWSCntMgmtCppWrapper.cs
<Source>\CAAENOVWSUtils.cs

The CAAENOVWSCntMgmtCppProxy.cs file contains the C# client binding generated using the wsdl.exe utility. A C# client binding consists of a proxy and several types definitions. The CAAENOVWSCntMgmtCppWrapper.cs file contains a class that describes how to configure the generated proxy and how to invoke its methods.

The CAAENOVWSDotNet1_1Client.m module (executable) contains the following resources:

<Source>\CAAENOVWSDotNet1_1Client.cs
<Source>\CAAENOVWSCntMgmtCppUseCase.cs

The CAAENOVWSDotNet1_1Client.cs file contains the main program. It parses the command line inputs and starts up the use case. The CAAENOVWSCntMgmtCppUseCase.cs file contains the sample use case scenario.

[Top]

How to Launch CAAENOVWSDotNet1_1Client

To run the CAAENOVWSDotNet1_1Client use case, you will need to build both CAAENOVWSDotNet1_1ClientBase.m and CAAENOVWSDotNet1_1Client.m modules. The use case code can be built using either the CAA V5 buildtime environment, or Visual Studio .NET 2003 as explained in [1].

You can then execute the command described below:

CAAENOVWSDotNet1_1Client -w <URI> -e <ENOVIA username> -u <Basic Authentication username> -p <Basic Authentication password> -t ENOVWSCntMgmtCpp

Here follows a sample command, to be updated with your own environment configuration:

CAAENOVWSDotNet1_1Client -w http://stophe1dsy.dsy.ds:9080/B17 -e cjk -u wpsadmin -p wpsadmin -t ENOVWSCntMgmtCpp

The same executable is used to launch all of the available ENOVIA CAA Web services use cases. The -t option is used to choose the target use case to run.

When building the modules with the CAA V5 buildtime environment, the CAAENOVWSDotNet1_1Client executable can be launched from the following location:

<Install>\CAAENOVWS.edu\intel_a\code\clr

[Top]

Step-by-step

The following section first explains how to generate the C# client binding for the ENOVWSCntMgmtCpp CAA Web service demonstrated. The remaining sections describe how to configure the generated proxy and how to consume the Web service:

  1. Creating the C# Client Binding
  2. Instantiating and Configuring the Generated Proxy
  3. Creating Documents
  4. Attaching Documents to Parts
  5. Checking In Documents
  6. Checking Out Documents
  7. Sample Usage Scenario

[Top]

Creating the C# Client Binding

Please refer to [2] for details on how to generate the C# client binding using the wsdl.exe utility.

Here follows a sample command in order to generate the C# client binding for the ENOVWSCntMgmtCpp CAA Web service:

wsdl /namespace:com.dassault_systemes.caaenovws.caaenovwsdotnet1_1clientgen.enovwscntmgmtcpp /username:wpsadmin /password:wpsadmin /out:CAAENOVWSCntMgmtCppProxy.cs http://stophe1dsy.dsy.ds:9080/B17/wsdl?service=urn:com:dassault_systemes:ENOVWSCntMgmtImpl:ENOVWSCntMgmtImpl:ENOVWSCntMgmtCpp

The server name, port, and context root URI information must be updated to match the server where the ENOVWSCntMgmtCpp CAA Web service has been deployed. The /username and /username options are required to authenticate on the Web server hosting the Web service.

[Top]

Instantiating and Configuring the Generated Proxy

In order to consume an implementation of the ENOVWSCntMgmtCpp CAA Web service deployed on a target Web server, you first need to instantiate the proxy generated using the wsdl.exe utility. This proxy must then be configured in order to manage authentication on the remote Web server, timeout, and session management. Maintaining the HTTP session state is mandatory when consuming ENOVIA LCA V5 CAA Web services.

The generated proxy class is used in order to marshall method calls and objects to SOAP requests, and to unmarshall SOAP responses to objects. The following code describes how to instantiate and configure it:

public class CAAENOVWSCntMgmtCppWrapper {
  private const string SERVICE_ID = "urn:com:dassault_systemes:ENOVWSCntMgmtImpl:ENOVWSCntMgmtImpl:ENOVWSCntMgmtCpp";
  private CAAENOVWSCntMgmtCppProxy proxy = null;

  public CAAENOVWSCntMgmtCppWrapper(
    CookieContainer container,
    string uri,
    string credUser,
    string credPwd,
    int timeOut) {
    proxy = new CAAENOVWSCntMgmtCppProxy();
   
    // Compute the SOAP endpoint URI value that bounds to the deployed
    // implementation of the ENOVWSCntMgmtCpp CAA Web service
    proxy.Url = uri + "servicerouter?service=" + SERVICE_ID;

    // Required for HTTP session state management
    proxy.CookieContainer = container; (1)

    // Required for the Basic Authentication mechanism
    ICredentials credentials = new NetworkCredential(credUser, credPwd);
    proxy.Credentials = credentials; (2)

    // Increase the default client time-out
    proxy.Timeout = timeOut; (3)
  }
}

(1): in order to maintain the HTTP session state between successive calls performed using either the same or multiple proxy instances, the CookieContainer property must be set on the proxy. This is mandatory in the context of ENOVIA LCA V5 CAA Web services,
(2): when security is enabled on the remote Web server, it is mandatory to set the Credentials property on the proxy. The values specified must match a valid set of credentials for the Basic Authentication mechanism,
(3): the default timeout value can be increased in order to avoid potential issues at runtime, such as losing the HTTP connection before receiving the SOAP responses. The value specified in the code is in milliseconds.

[Top]

Creating Documents

To create documents, you can use the following method available through the generated proxy interface:

public Status CreateDocument(ENOVIA iObjects, ref ENOVIA oObjects)

This method accepts the following parameters:

[in] iObjects   ENOVIA_VPMDocumentRevision object with a unique V_ID for ENOVIA_VPMTPDocumentMaster
[in/out] oUserContexts   Return the created document revision object

The following code demonstrates the use of the CreateDocument method:

public class CAAENOVWSCntMgmtCppWrapper {
  ...
  public ENOVIA CreateDocument(
    string docID,
    string docName,
    string domain) {
    if (docID == null) {
      throw new ApplicationException("Illegal argument: document ID is null");
    } else if (docName == null) {
      throw new ApplicationException("Illegal argument: document name is null");
    } else if (domain == null) {
      throw new ApplicationException("Illegal argument: document domain is null");
    }

    ENOVIA_VPMDocumentRevision vpmDocumentRevision =
      new ENOVIA_VPMDocumentRevision();
    vpmDocumentRevision.Domain = domain;
    vpmDocumentRevision.ENOVIA_VPMTPDocumentMasterV_ID = docID;
    vpmDocumentRevision.ENOVIA_VPMTPDocumentMasterV_name = docName;

    ENOVIA_VPMDocumentRevision[] vpmDocumentRevisions =
      { vpmDocumentRevision };
    ENOVIA input = new ENOVIA();
    input.ENOVIA_VPMDocumentRevision = vpmDocumentRevisions;
    ENOVIA resultSet = null;

    try {
      Status status = proxy.CreateDocument(input, ref resultSet);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to create document(s)", e);
    }

    if (resultSet == null) {
      throw new Exception("Failed to create document(s)");
    }
    return resultSet;
  }

  public string[] GetENOVIA_VPMDocumentRevisionUUIDs(ENOVIA resultSet) {
    if (resultSet == null) {
      throw new ApplicationException("Illegal argument exception: ENOVIA result set is null");
    }

    ENOVIA_VPMDocumentRevision[] vpmDocumentRevisions =
      resultSet.ENOVIA_VPMDocumentRevision;
    if (vpmDocumentRevisions == null) {
      throw new ApplicationException("Failed to retrieve ENOVIA_VPMDocumentRevision objects");
    }

    string[] vpmDocumentRevisionUUIDs =
      new string[vpmDocumentRevisions.Length];
    for (int i = 0; i < vpmDocumentRevisions.Length; i++) {
      vpmDocumentRevisionUUIDs[i] = vpmDocumentRevisions[i].CATJsyUUID;
    }
    return vpmDocumentRevisionUUIDs;
  }
}

The GetENOVIA_VPMDocumentRevisionUUIDs method is used to scan the ENOVIA result set returned and retrieve the UUIDs of the created documents.

[Top]

Attaching Documents to Parts

To attach documents to parts, you can use the following method available through the generated proxy interface:

public Status AttachDocument(Identifier iParentId, Identifier[] iDocumentIds, string iAttachType, string iDocRole)

A ENOVIA LCA V5 Part Object should be existing.

This method accepts the following parameters:

[in] iParentId   Part object identifier
[in] iDocumentIds   Document Identifier(s)
[in] iAttachType   "Representation" or "Documentation"
[in] iDocRole   "Primary" or "Secondary"

The following code demonstrates the use of the AttachDocument method:

public class CAAENOVWSCntMgmtCppWrapper {
  ...
  private Identifier ToIdentifier(string id) {
    if (id == null) {
      throw new ApplicationException("Illegal argument: identifier value is null");
    }

    Identifier identifier = new Identifier();
    identifier.Identifier1 = CAAENOVWSUtils.ConvertFromHexToBinary(id);
    return identifier;
  }

  private Identifier[] ToIdentifierArray(string[] ids) {
    if (ids == null) {
      throw new ApplicationException("Illegal argument: identifiers array is null");
    }

    Identifier[] identifiers = new Identifier[ids.Length];
    for (int i = 0; i < ids.Length; i++) {
      identifiers[i] = ToIdentifier(ids[i]);
    }
    return identifiers;
  }

  public void AttachDocument(
    string partUUID,
    string[] docUUIDs,
    string attachType,
    string role) {
    if (partUUID == null) {
      throw new ApplicationException("Illegal argument: part reference UUID is null");
    } else if (docUUIDs == null) {
      throw new ApplicationException("Illegal argument: document UUID array is null");
    } else if (attachType == null) {
      throw new ApplicationException("Illegal argument: attach type is null");
    } else if (role == null) {
      throw new ApplicationException("Illegal argument: role is null");
    }

    Identifier partId = ToIdentifier(partUUID);
    Identifier[] docIds = ToIdentifierArray(docUUIDs);

    try {
      Status status =
        proxy.AttachDocument(partId, docIds, attachType, role);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to attach document(s)", e);
    }
  }
}

[Top]

Checking In Documents

To check in documents, you can use the following method available through the generated proxy interface:

public Status CheckIn(Identifier iDocumentId, string iFileName, string iVaultName, byte[] iData, ref ENOVIA oResult)

This method accepts the following parameters:

[in] iDocumentId   The Document revision identifier
[in] iFileName   The desired doc filename
[in] iVaultName   The target vault name (optional, uses default)
[in] iData   Binary document file contents
[in/out] oResult   Modified Document file object and attributes

The following code demonstrates the use of the CheckIn method:

public class CAAENOVWSCntMgmtCppWrapper {
  ...
  public ENOVIA CkeckIn(
    string docUUID,
    string fileName,
    string vaultName,
    byte[] data) {
    if (docUUID == null) {
      throw new ApplicationException("Illegal argument: document UUID is null");
    } else if (fileName == null) {
      throw new ApplicationException("Illegal argument: filename is null");
    } else if (vaultName == null) {
      throw new ApplicationException("Illegal argument: Vault name is null");
    } else if (data == null) {
      throw new ApplicationException("Illegal argument: data byte array is null");
    }

    Identifier docId = ToIdentifier(docUUID);
    ENOVIA resultSet = null;

    try {
      Status status =
        proxy.CheckIn(docId, fileName, vaultName, data, ref resultSet);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to check in document(s)", e);
    }

    if (resultSet == null) {
      throw new Exception("Failed to check in document(s)");
    }
    return resultSet;
  }
}

[Top]

Checking Out Documents

To check out documents, you can use the following method available through the generated proxy interface:

public Status CheckOut(Identifier iDocumentId, ref byte[] oData, ref ENOVIA oResult)

This method accepts the following parameters:

[in] iDocumentId   Identifier of the Document Revision
[in/out] oData   Binary document file contents
[in/out] oResult   ENOVIA result set containing the checked-out document file object and attributes

The following code demonstrates the use of the CheckOut method:

public class CAAENOVWSCntMgmtCppWrapper {
  ...
  public ENOVIA CheckOut(string docUUID) {
    if (docUUID == null) {
      throw new ApplicationException("Illegal argument: document UUID is null");
    }

    Identifier docId = ToIdentifier(docUUID);
    ENOVIA resultSet = null;
    byte[] data = null;

    try {
      Status status = proxy.CheckOut(docId, ref data, ref resultSet);
      Console.Out.WriteLine("Status: {0}", status.Status1);
    } catch (Exception e) {
      throw new ApplicationException("Failed to attach document", e);
    }

    if (resultSet == null) {
      throw new Exception("Failed to check out document(s)");
    }
    return resultSet;
  }
}

[Top]

Sample Usage Scenario

The following code depends on:

It demonstrates a sample usage scenario for the ENOVWSCntMgmtCpp CAA Web service:

public class CAAENOVWSCntMgmtCppUseCase {
  private string uri = null;
  private string credUser = null;
  private string credPwd = null;

  public CAAENOVWSCntMgmtCppUseCase(
    string uri,
    string credUser,
    string credPwd) {
    this.uri = uri;
    this.credUser = credUser;
    this.credPwd = credPwd;
  }

  public void RunSampleUsageScenario(string enoviaUser) {
    enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper binderWrapper = null;
    enoposapplicationbinderimpl.SessionToken sessionToken = null;
    try {
      // ------------------------------------------------------------
      // Step 1 - Instantiate and configure the proxies
      // ------------------------------------------------------------

      // Create a CookieContainer object to maintain the HTTP session
      // state accross proxies
      CookieContainer container = new CookieContainer();

      // Instantiate wrapper client classes
      int timeOut = 360000;
      binderWrapper =
        new enoposapplicationbinderimpl.CAAENOPosApplicationBinderImplWrapper(
          container, uri, credUser, credPwd, timeOut);
      enovwsprodstructcpp.CAAENOVWSProdStructCppWrapper prodStructWrapper =
        new enovwsprodstructcpp.CAAENOVWSProdStructCppWrapper(
          container, uri, credUser, credPwd, timeOut);
      enovwscntmgmtcpp.CAAENOVWSCntMgmtCppWrapper cntMgmtWrapper =
        new enovwscntmgmtcpp.CAAENOVWSCntMgmtCppWrapper(
          container, uri, credUser, credPwd, timeOut);

      // ------------------------------------------------------------
      // Step 2 - Open session with ENOVIA LCA V5
      // ------------------------------------------------------------

      // Get user contexts
      string[] userContexts = binderWrapper.GetUserContexts(enoviaUser);

      // Log in using the first available context
      if (userContexts.Length == 0) {
        throw new ApplicationException("No context found for the user specified");
      }
      sessionToken = binderWrapper.Login(userContexts[0]);

      // ------------------------------------------------------------
      // Step 3 - Create 2 documents
      // ------------------------------------------------------------

      string docId1 = "CAAWSCnt1" + Environment.TickCount; // the VID has to be unique
      string docName1 = "Doc1" + docId1;
      string domain = "DOCDIR";

      enovwscntmgmtcpp.ENOVIA createDocResultSet1 =
        cntMgmtWrapper.CreateDocument(docId1, docName1, domain);

      string[] docUUIDs1 =
        cntMgmtWrapper.GetENOVIA_VPMDocumentRevisionUUIDs(
          createDocResultSet1);
      if (docUUIDs1.Length > 1) {
        throw new ApplicationException("Invalid state: more than 1 document was returned");
      } else if (docUUIDs1.Length != 1) {
        throw new ApplicationException("Failed to create the document");
      }
      string docUUID1 = docUUIDs1[0];

      CAAENOVWSUtils.DisplayResults(createDocResultSet1, 1);

      string docId2 = "CAAWSCnt2" + Environment.TickCount;
      string docName2 = "Doc2" + docId2;

      enovwscntmgmtcpp.ENOVIA createDocResultSet2 =
        cntMgmtWrapper.CreateDocument(docId2, docName2, domain);

      string[] docUUIDs2 =
        cntMgmtWrapper.GetENOVIA_VPMDocumentRevisionUUIDs(
          createDocResultSet2);
      if (docUUIDs2.Length > 1) {
        throw new ApplicationException("Invalid state: more than 1 document was returned");
      } else if (docUUIDs2.Length != 1) {
        throw new ApplicationException("Failed to create the document");
      }
      string docUUID2 = docUUIDs2[0];

      CAAENOVWSUtils.DisplayResults(createDocResultSet2, 1);

      // ------------------------------------------------------------
      // Step 4 - Create part
      // ------------------------------------------------------------

      string partNumber = "CAAWSCntPrt" + Environment.TickCount;

      enovwsprodstructcpp.ENOVIA createPartResultSet =
        prodStructWrapper.CreatePartRef(
          new string[] { partNumber }, "PRODUCT", "FALSE");

      string[] partRefUUIDs =
        prodStructWrapper.GetENOVIA_VPMPartVersionUUIDs(
          createPartResultSet);
      if (partRefUUIDs.Length > 1) {
        throw new ApplicationException("Invalid state: more than 1 part reference was returned");
      } else if (partRefUUIDs.Length != 1) {
        throw new ApplicationException("Failed to create part reference");
      }
      string partRefUUID = partRefUUIDs[0];

      CAAENOVWSUtils.DisplayResults(createPartResultSet, 1);

      // ------------------------------------------------------------
      // Step 5 - Attach document to part
      // ------------------------------------------------------------

      string attachType = "Primary"; 
        string role ="Documentation"; 
        string[] docUUIDs = { docUUID1, docUUID2 };

      cntMgmtWrapper.AttachDocument(partRefUUID, docUUIDs, attachType, role);

      // ------------------------------------------------------------
      // Step 6 - Check in document
      // ------------------------------------------------------------

      string fileName = "CAAFileTestForCntCheckIn.txt";
      string vaultName = "";
      string fileContent = "asasasasasaasasasasaskljadlkfhslkdfhsdlfhklsdh;asdhjl;dfhsdhjksdfhkshjkshjksdhfjksdhfjksd";
      byte[] data = (new UnicodeEncoding()).GetBytes(fileContent);

      enovwscntmgmtcpp.ENOVIA checkInResultSet =
        cntMgmtWrapper.CkeckIn(docUUID1, fileName, vaultName, data);

      CAAENOVWSUtils.DisplayResults(checkInResultSet, 1);

      // ------------------------------------------------------------
      // Step 7 - Check out document
      // ------------------------------------------------------------

      enovwscntmgmtcpp.ENOVIA checkOutResultSet =
        cntMgmtWrapper.CheckOut(docUUID1);

      CAAENOVWSUtils.DisplayResults(checkOutResultSet, 1);
    } catch (Exception e) {
      ...
    } finally {
      // ------------------------------------------------------------
      // Step 8 - Terminate opened session
      // ------------------------------------------------------------

      // The session must be closed even if a call to a method on the ENOVWSQueryCpp
      // CAA Web service fails
      binderWrapper.Logout(sessionToken);
    }
  }
}

The CAAENOVWSUtils.DisplayResults method can be found at:

<Source>\CAAENOVWSUtils.cs

[Top]

In Short

This use case explains how to use the C# client binding generated using the wsdl.exe utility in order to consume the ENOVWSCntMgmtCpp CAA Web service. It also gives an overview of the available method:

[Top]

References

[1] Building and Launching a CAA Web Service Use Case
[2] Generating a C# Client Binding
[3] Consuming the ENOPosApplicationBinderImpl CAA Web Service
[4] Consuming the ENOVWSProdStructCpp CAA Web Service
[Top]

History

Version: 1 [Jan 2006] Document created
[Top]

Copyright © 2006, Dassault Systèmes. All rights reserved.