> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document files

> How to create physical document from template; rename document; change file extension; edit document; delete document; check document in/out

The physical document is tied to the [NSDocumentEntity][1] and stored in the document archive.

## Create physical document from template

Which template to use is set in the document properties.

**Required IDs:**

* company (contact ID)
* person
* appointment
* document
* sale
* selection
* project
* uiCulture (used to select a template of the appropriate language, for example, "en-US" or "nb-NO")

<Tip>
  If set to **0**, the company, person, appointment, sale, and project IDs will default to the values set in the document properties.
</Tip>

```crmscript theme={null}
NSDocumentAgent agent;
NSDocumentEntity doc = agent.GetDocumentEntity(2);

agent.CreateNewPhysicalDocumentFromTemplate(doc.GetContact().GetId(), 0, 0, doc.GetDocumentId(),0,0,0,"");
```

## Filenames

The initial filename is taken from the document properties.

```crmscript theme={null}
NSDocumentEntity doc;
String filename = doc.GetName();
```

### Rename physical document

When renaming, you can **suggest** a new filename. The document archive may amend this if your suggestion is already used by another file, contains restricted characters, or similar.

```crmscript theme={null}
String newFilename = "Trebbles.doc";
Integer docId = 3;

NSDocumentAgent agent;
NSDocumentEntity doc = agent.GetDocumentEntity(docId);

String actualName = agent.RenameDocument(docId, newFilename);

doc.SetName(actualName);
agent.SaveDocumentEntity(doc);
```

<Tip>
  Don't forget to save the `NSDocumentEntity`!
</Tip>

### Change file extension

```crmscript! theme={null}
String changeFileExtension(Integer documentId, String extension) {

  NSDocumentAgent agent;
  NSDocumentEntity doc = agent.GetDocumentEntity(documentId);

  String newName = agent.RenameDocument(documentId, doc.GetName().beforeLast(".") + extension);
  doc.SetName(newName);
  agent.SaveDocumentEntity(doc);
  return(newName);
}

printLine(changeFileExtension(3, ".pdf"));
```

## Locked for editing

In SuperOffice CRM, many people are creating, editing, and reading documents at any given time. If multiple users are editing the same document at the same time, they risk overwriting each other's data. To prevent this from happening, SuperOffice CRM will lock a document when it is being edited by a user. Other users can still open the document, but only in read-only mode.

### Is the document checked out

```crmscript! theme={null}
NSDocumentAgent agent;
NSCheckoutInfo info = agent.GetCheckoutState(2);
printLine(info.GetState().toString() + "\t" + info.GetName());
```

### Check out

```crmscript theme={null}
String[] returnTypes;
NSDocumentAgent agent;
agent.CheckoutDocument(2, returnTypes);
```

### Undo (abandon) a checkout

```crmscript theme={null}
String[] returnTypes;
NSDocumentAgent agent;
agent.UndoCheckoutDocument(2, returnTypes);
```

### Check in

If the document or plug-in supports versioning, you can provide a description and metadata for a specific version when you check it in.

```crmscript theme={null}
String[] returnTypes;
String[] meta;

NSDocumentAgent agent;
agent.CheckinDocument(2, returnTypes, "updated copyright", meta);
```

## Edit physical document - online

File operations are unavailable in CRM Online. All updates happen through document plug-ins using a URL referring to the actual document.

<Tip>
  To update only the document properties, [update the NSDocumentEntity][1].
</Tip>

### Get URL

```crmscript! theme={null}
NSDocumentAgent agent;
Integer docId = 2;
String url = agent.GetDocumentUrl(docId, "", true);
printLine(url);
```

This example gets a writable URL for the latest version of document 2.

## Delete physical document

```crmscript theme={null}
String[] returnType;

NSDocumentAgent agent;
agent.DeletePhysicalDocument(5, returnType);
```

## Reference

### Return types (NSReturnInfo)

The document plugin might need to request additional processing. When deleting, you should pass a list of return types that the client is prepared to handle. If there are no restrictions, pass an empty array.

* CustomGui
* Message
* None
* Other
* SoProtocol

[1]: ./properties


## Related topics

- [Edit documents](/en/document/learn/edit.md)
- [SuperOffice.WebApi.Data.Document GetTempFileRequest](/en/api/reference/webapi/SuperOffice.WebApi.Data.Document_GetTempFileRequest.md)
- [SuperOffice.WebApi.Data.Document CreateTempFileRequest](/en/api/reference/webapi/SuperOffice.WebApi.Data.Document_CreateTempFileRequest.md)
- [SuperOffice.WebApi.Data.Document DeleteTempFileRequest](/en/api/reference/webapi/SuperOffice.WebApi.Data.Document_DeleteTempFileRequest.md)
- [File](/en/automation/crmscript/reference/CRMScript.Native.File.md)
- [Documents](/en/mobile/document/index.md)