> ## 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 properties

> How to retrieve document info; create a document entity; link document to a follow-up; change document properties; work with suggested documents.

## Retrieve document info

### To view basic info, use NSDocument

```crmscript! theme={null}
NSDocumentAgent docAgent;
NSDocument doc = docAgent.GetDocument(2);
printLine(doc.GetDocumentName());
```

### To view (and possibly update) complex info, use NSDocumentEntity

```crmscript! theme={null}
NSDocumentAgent docAgent;
NSDocumentEntity doc = docAgent.GetDocumentEntity(1);
printLine(doc.GetContact().GetName());
```

### List all documents with SearchEngine

```crmscript! theme={null}
SearchEngine se;
se.addFields("document", "document_id,name,header");
print(se.executeTextTable());
```

<Tip>
  If you know there's a lot of documents, consider adding a **count** criteria to limit the results.
</Tip>

### NSDocument\[] GetDocumentList(Integer\[] p0)

Fetches a collection of documents corresponding to a list of IDs.

```crmscript! theme={null}
Integer[] docIDs;
docIDs.pushFront(84);
docIDs.pushFront(86);
docIDs.pushFront(88);

NSDocumentAgent docAgent;
NSDocument[] docList = docAgent.GetDocumentList(docIDs);

for(Integer i = 0; i < docList.length(); i++) {
  printLine(docList[i].GetDocumentId().toString());
}
```

### NSDocument\[] GetAppointmentDocuments(Integer appointmentId)

Get all documents that are linked to a follow-up.

```crmscript theme={null}
Integer appointmentId = 4;
NSDocumentAgent docAgent;
NSDocument[] docList = docAgent.GetAppointmentDocuments(appointmentId);
```

### NSDocument\[] GetContactDocuments(Integer contactId, DateTime startTime, DateTime endTime, Integer count)

Fetches a limited number of documents within a time range for the given contact.

```crmscript theme={null}
NSDocumentAgent docAgent;
DateTime start;
DateTime end;

NSDocument[] docList = docAgent.GetContactDocuments(4, start.addMonth(-6), end, 10);
```

<Tip>
  Set `count` to -1 to not restrict the collection of documents retrieved.
</Tip>

## Create document entity

### NSDocumentEntity CreateDefaultDocumentEntity()

Create and populate with default values:

```crmscript! theme={null}
NSDocumentAgent agent;
NSDocumentEntity doc = agent.CreateDefaultDocumentEntity();

doc.SetHeader("Test document");
doc.SetName("Test.doc");

doc = agent.SaveDocumentEntity(doc);

printLine(doc.GetDocumentId().toString());
```

### Set document properties for people and organizations

You can choose whether to use an agent to get associate, contact, and person objects by their ID or to create the objects and set the ID.

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

NSAssociate owner;
owner.SetAssociateId(13);
doc.SetAssociate(owner);

NSContact c;
c.SetContactId(2);
doc.SetContact(c);

NSPersonAgent personAgent;
NSPerson p = personAgent.GetPerson(5);
doc.SetPerson(p);

doc = agent.SaveDocumentEntity(doc);
```

Read more about [working with persons and organizations][4].

## Link document to a follow-up

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

NSAppointmentAgent appAgent;
NSAppointmentEntity a = appAgent.CreateDefaultAppointmentEntity();

a.SetDescription(doc.GetHeader());
a.SetContact(doc.GetContact());

NSLink link;
link.SetEntityName("document");
link.SetId(doc.GetDocumentId());

NSLink[] links;
links.pushBack(link);

a.SetLinks(links);

appAgent.SaveAppointmentEntity(a);
```

## Suggested documents

Suggested documents are just that  - **suggested**. They're blueprints that can be used to create actual documents, and are commonly used for [sales guides][2] and project guides.

<Note>
  Don't confuse suggested documents for [document templates][1].
</Note>

### List available suggestions

```crmscript! theme={null}
SearchEngine se;
se.addFields("SuggestedDocument", "SuggestedDocument_id,name,saleTypeStageLinkId,projectTypeStatusLinkId");
print(se.executeTextTable());
```

### Create document from suggestion

All you need is the ID of the suggested document, and then calling `CreateDefaultDocumentEntityFromSuggestion()` will do the magic for you!

```crmscript! theme={null}
NSDocumentAgent agent;
NSDocumentEntity doc = agent.CreateDefaultDocumentEntityFromSuggestion(3);
doc = agent.SaveDocumentEntity(doc);

printLine(doc.GetDocumentId().toString() + "\t" + doc.GetHeader());
```

## Change document properties

<Note>
  The `NSDocumentEntity` can't be changed if the document is marked as **Completed**.

  Use `GetCompleted()` to check the status. Toggle it to **0** to do your edits and then toggle it back if necessary.
</Note>

```crmscript theme={null}
NSDocumentAgent agent;

NSDocumentEntity doc = agent.GetDocumentEntity(2);

if (doc.GetCompleted() == 3) {
  doc.SetCompleted(0);
  doc = agent.SaveDocumentEntity(doc);
}
```

## Delete document entity

```crmscript theme={null}
NSDocumentAgent agent;
agent.DeleteDocumentEntity(99);
```

## Reference

### Frequently used fields

| Field           | Description                             |
| :-------------- | :-------------------------------------- |
| document\_id    | ID                                      |
| application\_id | application this document was made with |
| name            | filename with extension                 |
| header          | visible document name aka title         |
| our\_ref        | our reference (internal)                |
| your\_ref       | your reference (external)               |
| appointment\_id | points back to owning appointment       |

For a complete list of fields, see the [database reference][3].

<Tip>
  Both `our_ref` and `your_ref` are strings.
</Tip>

[1]: ./templates

[2]: ../sale/guides

[3]: ../../../../database/tables/document

[4]: ../contact/index


## Related topics

- [Get Document Properties](/en/api/reference/restful/agent/document_agent/get-document-properties.md)
- [Edit documents](/en/document/learn/edit.md)
- [Document files](/en/automation/crmscript/howto/document/file.md)
- [Create document](/en/mobile/document/create.md)
- [Document events](/en/automation/webhook/reference/document-events.md)