| Applies to: This article applies to DocuShare only. It does not apply to DocuShare Flex, which has its own CIM behavior and a separate best practices article. |
| Scope: This article applies only to CIM sockets that use XML or CSV metadata files. It does not apply to simple CIM sockets that use flat files without metadata. |
| Support scope and DSDN requirement: Distribution and use of the CIM Config Tool requires a DocuShare Developer Network (DSDN) subscription. Setup and configuration of Advanced CIM sockets that use metadata files for ingestion falls outside the scope of standard support. Standard support can provide basic troubleshooting of known issues, review this best practices guidance, and assist if a previously working and configured socket stops working. Support beyond that scope, depending on the issue, requires an active DSDN subscription, a Professional Services engagement, or both. |
Before You Configure the Socket
- Confirm that the errorDirectory location for the socket is explicitly configured. Unlike some other CIM socket types, an XML or CSV metadata socket does not fall back to a default error directory if one is not specified, and the socket can fail to initialize without it.
- Confirm the error directory exists and that the DocuShare service account has permission to create and write files in it.
Recommended Order of Operations
The example below uses a CSV metadata file. The same order applies to XML metadata files.
- Upload the transform file first, before configuring the socket.
- Copy the content files, such as PDFs, to the watch folder.
- Copy the metadata file last, using the temporary-extension technique below.
Copying the Metadata File Safely
Copy the metadata file to the watch folder using a non-triggering extension first, then rename it. This prevents CIM from starting to process the file while it is still being written or is still in transit to the watch folder.
- Copy the file to the watch folder with a temporary extension, for example metadata.csv.tmp.
- Rename metadata.csv.tmp to metadata.csv once the copy is complete. Renaming triggers ingestion.
File Naming and Batch Practices
- Do not reuse the same file name across different batches. Reusing a name risks overwriting a file still in the watch folder from a previous batch. Use a unique name per batch, for example by appending the batch name or a timestamp to each file name.
- Keep batches to a manageable size, such as 500 to 1,000 files per metadata file. Larger batches are harder to diagnose if an error occurs partway through processing.
Monitoring and Error Handling
- Review the configured error directory for files that failed processing. Files placed there are renamed with a timestamp and counter prefix ahead of the original file name, so you can correlate an error file back to its source file and batch.
- Periodically clear the contents of the error directory to free disk space. For CIM sockets using XML or CSV metadata files, there is no automatic, time-based cleanup of the error directory. Files remain there until removed manually.
Support Guidance
Setup and configuration of Advanced CIM sockets that use metadata files is outside the scope of standard support. Standard support covers basic troubleshooting of known issues, this best practices guidance, and assistance if a previously working socket stops working. If your issue requires configuration or setup assistance beyond that scope, an active DSDN subscription, a Professional Services quote, or both may be required.
If ingestion fails or behaves unexpectedly within standard support scope, gather the following before contacting DocuShare Support:
- The socket configuration, including the watch folder, errorDirectory, and transform file in use.
- The exact batch or metadata file name and approximate file count in the affected batch.
- Any files present in the error directory for the affected time window, including their timestamp-prefixed names.
- The relevant ingester service logs covering the time of the failure.
Important Information
This article applies to DocuShare only. If you are running DocuShare Flex, refer to the separate DocuShare Flex CIM best practices article, since socket behavior, configuration, and error handling can differ between the two products.