EdiPortalReceive.svc

The EdiPortalReceive is a SOAP service build upon WCF.

The link for the service is: http://link-to-receive-site.yourdomain.com/EdiPortalReceive.svc

Shared for both Inbox and Outbox

Credentials

All methods in this service takes a UserCredentials object as an input parameter. Before it's possible to communicate with the EdiPortalReceive.svc service, a Link user must have been created for the purpose.

UserCredentials object

The UserCredentials object exposes more properties than needed, but it is only the username and password properties that are relevant.

string Username
string Password

Permissions

Outbox

When downloading documents from Link, the user must have the following permissions:

• "ReceiveSite Action Download" - required
• "AllowGetFromMultiplePartners" - optional (used if it should be possible to download documents from other partners than the one set on the user)

There are other permissions requried for some of the methods. See the description of the methods to find out if any specific permissions are required.

Inbox

When uploading documents to Link, the user must have the following permissions:

• "ReceiveSite Action Upload" - required
• "AllowSendFromMultiplePartners" - optional (used if it should be possible to upload documents for other partners than the one set on the user)

See "Settings" for further information about how to set permissions.

Outbox

This section describes how to download documents from Link that are in status "Outbox".

The above diagram shows the flow when downloading documents from Link

Method descriptions

There are several overloads for each method, so it's easier to handle more than one file at a time.

GetOutboxFile / GetOutboxFiles / GetOutboxFilesFromSettings

Description: 

This is the first method that should be called and the method that actually downloads the file(s) which are in status "Outbox".

When this method returns the affected documents in Link will have the status: "Processing".

Input parameters:

UserCredentials and the following properties wrapped in a OutboxSettings object:

string DistributionObjectName // Optional - If provided, only documents with this specific DistributionObjectName (document type) will be returned
string EdiPortalId            // Optional - If provided, documents for the partner with that EdiPortalId will be downloaded
int MaxNumberOfFiles          // Optional - Default 1
string TransportTypeName      // Optional - If provided, documents that have that specific transport-type set will be downloaded

There are some overload methods that takes some of the above properties directly as parameters, but the meaning of them remains the same as described.

Return value:

An array of OutboxFiles that contains the following properties:

long DocumentId // The unique id for this document - this id is used when calling the following confirm methods
byte[] FileData // The raw data for the InterchangeOut file
string FileName // The filename

ConfirmOutboxFileReceived / ConfirmOutboxFilesReceived

Description:

Right after the files have been downloaded, this method should be called to confirm the download.

When this method is called, the document(s) in Link will get a new Technical Status: "RetrievedFromOutbox"

This is done, so it is possible to trace the download process in Link (under document status).

Input parameters:

UserCredentials and the document-id(s) to confirm

long[] documentIds // An array of id's for the downloaded documents

Return value:

None

ConfirmOutboxFileDelivered / ConfirmOutboxFilesDelivered

Description:

Whenever the downloaded document(s) have been successfully handled by the system downloading them, this method should be called to tell Link, that the documents can be completed.

"Successfully handled" could for instance be, that they have been delivered to another software-system, file-system, etc..

When this method is called the document(s) in Link will have the following status: 

• TransferCompleteFromOutbox (technical status)
• Completed (final status)

Input parameters:

UserCredentials and the document-id(s) to complete

long[] documentIds // An array of id's for the downloaded documents that have been successfully handled

Return value:

None

MarkFileFailed / MarkFilesFailed

Special permissions required for calling this method: 

• ReceiveSite_Action_FailDocuments

Description:

If an error occurrs client-side in the download process or if the client for some reason rejects the document(s), the client can fail the document(s) in Link by calling this method.

After calling this method the document(s) will have status: "Failed" in Link

Input parameters:

UserCredentials, the document-id(s) to fail and an error message

long[] documentIds  // An array of id's for the downloaded documents that should be failed in Link
string errorMessage // The error message that describes why the client has failed the document. This will also be the status message on the document.

Return value:

None

MarkFileFailedWithErrorCode / MarkFilesFailedWithErrorCode

Special permissions required for calling this method: 

• ReceiveSite_Action_FailDocuments

Description:

This method behave the same as the above (MarkFileFailed), but with an extra option of specifying an error-code

Input parameters:

UserCredentials, the document-id(s) to fail, an error message and an error code

long[] documentIds  // An array of id's for the downloaded documents that should be failed in Link
string errorMessage // The error message that describes why the client has failed the document. This will also be the status message on the document.
int errorCode       // The Link error code to connect to the document

Return value:

None

MarkFileOutbox / MarkFilesOutbox

Special permissions required for calling this method: 

• ReceiveSite_Action_MarkFilesOutbox

Description:

If the client for some reason needs to re-download the document(s), they can be set back to status "Outbox" by calling this method.

Input parameters:

UserCredentials, the document-id(s) to set back to status "Outbox" and a comment

long[] documentIds  // An array of id's for the downloaded documents that should be failed in Link
string comment      // The comment that should be set on the document status when setting it to "Outbox"

Return value:

None

Inbox

This section describes how to send documents to Link.

Shared objects

The following are objects that are re-used across the different upload methods.

EdiPortalConfig

This configuration object is used in all the methods used for uploading. It gives Link details about the uploaded documents

string DistributionObjectName // The name of the document type of the uploaded documents
string SenderEdiPortalId      // EdiPortalId for the sender of the document(s). To set this to another id than the users default partner, requires the "AllowSendFromMultiplePartners" permission
string ReceiverEdiPortalId    // EdiPortalId for the receiver of the document(s)
string OriginatingSystemName  // Currently not supported!
string FormatName             // Name of the Format for the document(s)
string VariantName            // Name of the Variant for the document(s) 
string VariantVersionName     // Name of the Variant Version for the document(s)
string FormatTypeName         // Name of the FormatType for the document(s) - eg. Edifact, Xml or Edi
string PortConfiguration      // Xml based configuration that can be used to give information to the pipeline. See example below.

Example of PortConfiguration xml:

<EdiPortalRcvComponent>
    <Property>
        <Name>JsonRootNode</Name>
        <Value>Invoice</Value>
    </Property>
    <Property>
        <Name>JsonRootNodeNameSpace</Name>
        <Value>urn:oasis:names:specification:ubl:schema:xsd:Invoice-2</Value>
    </Property>
</EdiPortalRcvComponent>

Result

The result is quite simple, and contains only a single property.

string InterchangeGuid // The Unique Identifier the Link has given the uploaded document.

UserCredentials

See description in the first section

Method descriptions

Sending documents to Link is a more simple process than downloading, since this can be done in a single call.

There are different ways of uploading the documents, as described in the following methods. Choose the one that fits your needs.

SendFileToInbox

Description:

If the document to upload is represented in a binary way, this method should be used.

Input parameters:

UserCredentials, EdiPortalConfig and InboxFile

InboxFile:

byte[] FileData           // Required - The raw binary data of the document
bool IsZipped             // Required - A value indicating whether the raw data is zipped
string FileName           // Optional - The filename of the document. If not set a Guid will be created as the filename (eg. "A4098BDC-AEDE-44CE-9D65-ED4979DC3E03.in")
string InterchangeNumber  // Optional - An interchange number for the document

Return value:

An instance of the "Result" object - see the Shared Objects section for further information.

SendFileToInboxString

Description:

If the document to upload is represented as a string in the client, this method could be used to upload the document.

Input parameters:

UserCredentials, EdiPortalConfig and InboxFileString

InboxFileString:

string FileContent        // Required - The data of the document represented as a string
string ContentEncoding    // Optional - (default UTF8) The encoding of the content-string
string FileName           // Optional - The filename of the document. If not set a Guid will be created as the filename (eg. "A4098BDC-AEDE-44CE-9D65-ED4979DC3E03.in")
string InterchangeNumber  // Optional - An interchange number for the document

Return value:

An instance of the "Result" object - see the Shared Objects section for further information.

SendFileToInboxXml

Description:

If the document to upload is represented as an XML-string in the client, this method could be used to upload the document.

Input parameters:

UserCredentials, EdiPortalConfig and InboxFileXml

InboxFileXml:

string XmlContent         // Required - The data of the document represented as an xml string
string FileName           // Optional - The filename of the document. If not set a Guid will be created as the filename (eg. "A4098BDC-AEDE-44CE-9D65-ED4979DC3E03.in")
string InterchangeNumber  // Optional - An interchange number for the document

Return value:

An instance of the "Result" object - see the Shared Objects section for further information.